Product Documentation

PDK 8.0 Documentation

PerlCtrl - Graphical Interface

The graphical interface to PerlCtrl provides full PerlCtrl functionality via a graphical front end.

Overview of the Interface

The drop-down menus are used to save and load project files containing PerlCtrl configuration details, and to set default display properties.

Drop-Down Menus

File menu

New: To return the settings on each of the tabs to their default state, select File|New. If there is an open project, it is closed.
Open Project: To load a previously saved PerlCtrl project, select File|Open Project. Project files are created via the Save Project or Save Project As menu items, and have a .perlctrl extension. When opening a project, all configuration items are set according to the configuration saved in the project file.
Open Script: To load a Perl script without an associated configuration, select File|Open Script.
Save Project: To save the current configuration, select File|Save Project. The project file is updated with recent changes.
Save Project As: If the current configuration was loaded from a project file, use File|Save Project As to save the project to a new filename. If a Perl script was opened, use File|Save Project As to create a new project file for it.
Recent Files: This provides shortcuts for opening recently visited projects and scripts.
Make Control: This generates the output control. Equivalent to the Make Control button.
Exit: To close PerlCtrl, select File|Exit.

View menu

Source Line Context: On the Files tab, when a module is selected, context information from the program or module that uses or requires the module is displayed in the right pane. The Source Line Context setting determines the number of context lines from the calling source file that are displayed.
Line Numbers: On the Files tab, when a module is selected, the lines that are relevant to the script dependencies are numbered.
Wrapped Output Lines: If this option is enabled, information about the build process displayed in the Output field of the Output tab is wrapped. Otherwise, long lines generate a scroll bar.

Help menu

Contents: Display the PerlCtrl reference.
PDK User Guide: Display the user guide in a new browser window.
Web Resources: Click a sub-menu item to report a bug in the Perl Dev Kit section of ActiveState's bug database, or to visit the Perl Dev Kit, ActivePerl, or ActiveState home pages.
About PerlCtrl: Display copyright, license and version information.

The tabs (Main, Files, Size, Options 1, Options 2, Version, Output) are used to configure build information for the output control. The tabs are described individually below.

Configuring PerlCtrl Build Parameters

Main Tab

The Main tab is used to specify the source script and configure general parameters for the project.

Project: Specify the PerlCtrl project by clicking the folder button to browse the filesystem.
Script: Specify the source Perl script by clicking the folder button to browse the filesystem.; This option corresponds to the --script scriptname command-line option.
Control: Specify a name and directory location for the output file. By default, this field is populated with the name of the input Script file (with an .exe extension on Windows) and is stored in the build directory. Click the 'browse' button to specify a different filename or path, or manually enter the path and/or name in the Control field.; This option corresponds to the --exe filename command-line option.
Target: Choose the target platform for the executable from the drop list. The current platform ("native") is the default. If PerlApp does not have a cached copy of ActivePerl for the target platform, a copy will be downloaded from ActiveState and installed in a local cache of cross-platform build components when Make Executable is run or when the Files tab is selected. Required modules will also be automatically installed in this cache.
Build directory: The output directory for the generated control. All relative filenames and paths are resolved from this location. Click the 'browse' button to navigate to a different location.
Perl: The location of the Perl executable. Click the 'browse' button to specify a different filename or path.

Module Search Path

The Module Search Path field displays the directories and libraries that are searched for modules used by the application. The default Perl search path directories are always at the end of the search path, and cannot be deleted.

To add directories or libraries to the search path, click Add. Specify the desired directory or file in the Path field, or click the 'browse' button to select a directory or file via file system navigation. Select Blib search to specify modules stored in 'MakeMaker'-style directory structures; for example, modules containing C code that must be compiled, rather than pure Perl modules. Select Shared executable to look for modules from a pre-built library file.

Additions to the module search path are added to the beginning of the list. To alter the search order, either Edit an existing entry or delete and re-add directories in the desired order. The Edit button is also used to toggle the Blib search status for a directory. To remove a directory or file, select the desired directory and click Delete.

The keyboard keys can also be used to navigate, add, edit and delete entries. The Insert key brings up the 'add' dialog box. The Enter key brings up the 'edit' dialog box for the currently selected entry. The Delete key deletes the currently selected entry.

These options correspond to the --lib libpath, --blib libpath and --use libname command-line options.

Files Tab

The Files tab is used to view, add and remove components from the output control. Component types are organized into 'containers' in the left pane; the right pane displays information about the item selected in the left pane. Click top-level component containers ('Script', 'Added modules', etc) to view a description of the component type. Click individual items in component containers to view information about specific components. For example, click a module name in the 'Script' container to view the source of the module reference, the relevant snippet of code, and links to a read-only display of the relevant files.

Each component type (described in individual sections below) has a context-sensitive menu that is invoked by right-clicking. The context menus are used for manipulating components. For example, right-click the Added modules container to add a new module; right-click a specific module contained in the 'Script' container to remove a module, or to view a module's source code.

When a module name is red, it indicates that the module was not found in the Module Search Path configured on the Main tab.

Script Container

The source script specified on the Main tab is analyzed to determine its 'dependencies' - that is, the modules the source script requires, and modules required by those modules. These modules are displayed in the 'Script' container.

Right-click the 'Script' container to display a context menu with the following options:

View source script: This option displays a window containing a read-only version of the source file specified on the Main tab.
Rescan: After editing the source script or a required module, use the Rescan option to refresh the list of required modules.
Expand 2 levels: This option expands the first two levels of the module hierarchy.
Open new script: This option replaces the file specified in the Script field on the Main tab with the selected file. This has the same effect as selecting File|Open Script from the main menu.

Required modules are displayed beneath the script container in a hierarchical structure, with module dependencies nested under the modules that require them. Right-click a specific module to display a context menu with the following options:

View module: Select this option to display a read-only window containing the source code for the selected module.
Trim module: To remove a module from the list of modules to be included in the output control, select Trim module. The module is added to the Module trim list on the Size tab.
Trim all prefix: To remove all modules with the same prefix as the current module, select Trim all prefix. An entry is added to the Module trim list on the Size tab.; This menu entry is only available if there are other modules included with a module name prefix shared with the current module.
Expand 2 levels: This option expands the first two levels of the module hierarchy beneath the module where it was invoked.

Added Modules Container

The Added modules container stores modules that are manually added to the project. Modules must be manually added if the PerlCtrl dependency checker fails to recognize that they are required. Right-click Added modules to display a context menu with the following options:

Add module: Specify the desired modules in the standard format, such as IO::Socket. PerlCtrl automatically tries to fix case mismatches.
Empty added modules: To remove all modules in the Added modules container, select Empty added modules from the context menu.

The added modules displayed directly beneath the Added modules container will have the context menu entry Remove module from added modules instead of the Trim... entries described for the modules under the Script container. Select this entry to get rid of added modules one by one.

The Added modules container corresponds to the --add modules command-line option.

Bound Files Container

To include additional files in the output control (accessed via the PerlCtrl::get_bound_file() and PerlCtrl::extract_bound_file() functions), use the Bound files container.

The Bound files container corresponds to the --bind file command-line option.

Right-click to display a context menu containing the following options:

Add bound file: Clicking this command displays a dialog box with options for specifying additional files to include in the control. This dialog have the following fields:
Empty bound files: To remove all files in the Bound files container, select Empty bound files from the context menu.

Icon Sources Container

Use the Icon sources container to specify icon files to include in the output control. This option is only applicable to Windows (use .ico, .dll, or .exe files) and Mac OS X (use .icns files). The right pane shows previews only for Windows icon files.

Right-click for a context menu with the following options:

Add Icon Source: Use this option to select icon files to include in the output control.
Remove icons: Use this option to remove all icon files.

This setting corresponds to the --icon command-line option.

Scanned Scripts Container

PerlCtrl can be instructed to scan extra scripts so that their dependent modules are included in the generated control. Right-click for a context menu with the following options:

Add Scanned Scripts: Selecting this option displays a dialog box used to specify one or more scanned scripts.
Remove Scanned Scripts: Use this option to remove all scanned scripts.

Implicit Modules Container

Some core modules are required implicitly by the use of specific code constructs. These modules are listed in the Implicit modules container. Right-click to access this option:

Expand 2 levels: This option expands the first two levels of the module hierarchy.

Size Tab

Control size

The Size tab contains options that can be used to affect the size of the output control.

Make dependent control: A 'dependent' control can only be run on systems where Perl and any required modules (as applicable) are already installed. Modules included from directories specified in the Module Search Path field on the Main tab or explicitly added on the File tab are included regardless of this setting.; This option corresponds to the --dependent and --freestanding command-line options.
Exclude perl*.dll from control: If perl56.dll, perl58.dll, or perl510.dll is installed on the system where the control is run, it can be excluded from the output control. .; This option corresponds to the --xclude command-line option.
Don't compress files in control: If the contents of the output control are compressed, the control will be smaller but may run less quickly because components must be decompressed before they are parsed.; This option corresponds to the --nocompress command-line option.

Module Trim List

The Module Trim List is used to specify modules that should be excluded from the output control.

To add a module or sub-modules to the list, click Add. Specify the name of the module in the Module field. Select the appropriate option button to include the Specified module only, Specified module and sub-modules, Sub-modules one level down only, or Sub-modules only. Use the Edit and Remove buttons to change or delete existing list items.

The keyboard keys can also be used to navigate, add, edit and delete entries. The Insert key displays the 'add' dialog box. The Enter key displays the 'edit' dialog box for the currently selected entry. The Delete key deletes the currently selected entry.

This option corresponds to the --trim modules command-line option.

Options 1 Tab

Debugger

To create a debug control, specify debugging parameters as described below.

Select debugger: From the drop-down list, select the debugger that you want to use. None creates a normal, as opposed to debug-able, control. PDK Debugger uses the graphical debugger included with the Perl Dev Kit. Remote PDK Debugger uses an instance of the Perl Dev Kit debugger installed on a different machine. Use Custom to specify an alternate debugger, such as Komodo's Perl debugger. The defaults in the Host and Port fields vary according to which option is selected.
Host: For debugging with a local instance of the PDK debugger, specify '127.0.0.1'. To debug the control with an instance of the PDK debugger running on a remote machine, specify the hostname of the remote machine, and the port on which the remote debugging instance is 'listening'. To use a 'custom' debugger, refer to the debugger's documentation for connection information.
Port: The default debug port for the Perl Dev Kit is '2000'.

These options correspond to the --debug host:port command-line option.

Temporary Directory

The temporary directory is used by the control to store temporary files extracted from the control.

Specify Temporary Directory: Select Use default temporary directory to use the temporary directory identified as the system's default according to the TEMP (Windows) or TMPDIR (Unix) environment variable. Select Use custom temporary directory to specify an alternate directory for storing temporary files.; This option corresponds to the --tmpdir path command-line option.
Clean Up Temporary Files: To automatically delete temporary files after the control terminates, select Clean up temporary files when the control terminates.; This option corresponds to the --clean command-line option.

Run Library

Select the Use run library option to specify an external directory relative to the control used to look up additional modules and DLLs at runtime. The default is to Use no run library.

These options correspond to the --runlib and --norunlib command-line options.

Options 2 Tab

Sharing of Control

The generated control can be shared so that other controls can make use of its modules and bound files. The default does not share the generated control, but you can choose to share it only with controls generated by your own PDK license or with all other controls.

These options correspond to the --shared command-line option.

Manifest

Windows application manifests can be used to request the new version of the common controls on Windows XP (and later), request administrative privilege elevation on Windows Vista (and later), or specifying binding instructions for other runtime libraries.

Use the default manifest (recommended): Embeds PerlApp's default manifest, which includes a requestedExecutionLevel value of "asInvoker".
Use no manifest: Windows will run the application with the old common controls.; This option corresponds to the --nomanifest command-line option.
Use manifest ...: Specify a custom manifest. Documentation on the application manifest XML file format can be found here:; http://msdn.microsoft.com/en-us/library/bb756929.aspx; This option corresponds to the --manifest command-line option.

Miscellaneous

Don't print version and copyright info: If this option is selected, version and copyright information are not displayed in the Output tab.; This option corresponds to the --nologo command-line option.
Verbose logging during run: If this option is enabled, the Output tab displays more information as the control is built.; This option corresponds to the --verbose command-line option.
Display all warnings: If this option is selected, all warnings messages will be displayed in addition to errors. These warnings will mostly be about optional modules that may be required by the program, but aren't installed on the machine.; It is not necessary to select this option when verbose logging has been enabled, which already contains all optional warnings as well.; This option corresponds to the --warnings command-line option.
Overwrite control if already exists: Select this option to prevent PerlCtrl from asking whether existing output files should be overwritten by new builds. If this option is not enabled, you will be prompted to confirm the overwrite when building the output control.; This option corresponds to the --force command-line option.
Use the in-memory dynamic DLL-loader at runtime: Select this option to have PerlCtrl use an internal library loader to load libraries directly into the process space without writing them to a temporary directory. This avoids cluttering the hard disk with temporary files, prevents problems that could arise when two applications try to extract the same file at the same time, and improves application security.; This option corresponds to the --dyndll command-line option.
Pass references as Win32::OLE::Variant objects: Select this option to pass all "by reference" parameters to Perl code as Win32::OLE::Variant objects instead of converting them to native values. PerlCtrl then implicitly loads the Win32::OLE::Variant module, so that using the parameters in number or string context will work normally. The control can use the Put() method of the parameter to change the caller's value of the argument. However, simple assignment to the parameter variable will not be propagated back to the caller.

Version Tab

Use the Version tab to configure the information that is displayed to users when they view the properties of the output control.

This option corresponds to the --info name = val ; ... command-line option.

Output Tab

The Output tab is used to generate the output control according to the specifications on the other tabs. The command string (corresponding to the command-line version of PerlCtrl) is displayed in the PerlCtrl Command Line field. Click the Make control button to generate the control; build messages are displayed in the Output field. The verbosity of output is determined by the Verbose logging during run setting on the Options 2 tab.

If the control was generated, then the Output field will have a link that can be used to test or debug the generated control. This starts the control without any command-line arguments. If arguments must be provided, start the control from the command line.