Product Documentation

PDK 7.2 Documentation

PerlNET - Graphical Interface

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

Overview of the Interface

The drop-down menus are used to save and load project files containing PerlNET 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 PerlNET project, select File|Open Project. Project files are created via the Save Project or Save Project As menu items, and have a .plc 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.
Make Target: This generates the output target in the same manner as clicking the Make Target button on the Output tab.
Recent Files: This provides shortcuts for opening recently visited projects and scripts.
Exit: To close PerlNET, 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 PerlNET reference.
Describe Current Tab: Display usage help for the tab that is currently displayed.
PDK User Guide: Display the user guide in a new browser window.
Web Resources: Click a submenu 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 PerlNET: 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 target. The tabs are described individually below.

Configuring PerlNET Build Parameters

Main Tab

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

Project: Specify the PerlNET 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.
Target: 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 Target field.; This option corresponds to the --exe filename command-line option.
Build directory: The output directory for the generated target. 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 prebuilt 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 target. 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 target, 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 PerlNET 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. PerlNET automatically tries to fix case mismatches.
Emtpy added modules: To remove all modules in the Added modules container, select Emtpy 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 target (accessed via the PerlNET::get_bound_file() and PerlNET::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 target. This dialog have the following fields:
Empty bound files: To remove all files in the Bound files container, select Emtpy bound files from the context menu.

Icon Sources Container

Use the Icon sources container to specify icon files to include in the output application.

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 application.
Remove icons: Use this option to remove all icon files.

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

Scanned Scripts Container

PerlNET 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

Target size

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

Make dependent target: A 'dependent' target 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 explictily 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 target: If perl56.dll, perl58.dll, or perl510.dll is installed on the system where the application is run, it can be excluded from the output target. .; This option corresponds to the --xclude command-line option.
Don't compress files in target: If the contents of the output target are compressed, the target 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 target.

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 application, 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 debuggable, application. 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 application 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 target to store temporary files extracted from the target.

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 application terminates, select Clean up temporary files when the target 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 target 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 Target

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

These options correspond to the --shared 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 application is built.; This option corresponds to the --verbose command-line option.
Overwrite target if already exists: Select this option to prevent PerlNET 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 target.; This option corresponds to the --force command-line option.
Use the in-memory dynamic DLL-loader at runtime: Select this option to have PerlNET 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.
Hide console (GUI target): To build a .NET application that does not open a console window, select this option.; This option corresponds to the --gui command-line option.

Version Tab

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

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

Output Tab

The Output tab is used to generate the output application according to the specifications on the other tabs. The command string (corresponding to the command-line version of PerlNET) is displayed in the PerlNET Command Line field. Click the Make target button to generate the application; 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 target was generated, then the Output field will have a link that can be used to test or debug the generated target. This starts the target without any command-line arguments. If arguments must be provided, start the target from the command line.