Main Site Contents Previous Next

Create Executable


Citrus Perl allows you to create dependent executables that may be created in either ../pathtoperl/bin or ../pathtoperl/apps.

Typically you might do this so that you can wrap your script as a gui executable on Windows or as a MacOSX application bundle. You might use Citrus Perl as the basis for distributing your applications as a single installable archive.

The source code for the executables is included at ../pathtoperl/citrus/src and you might like to take a look at the source for this utilities application in ../pathtoperl/vendor/CP and ../pathtoperl/vendor/Citrus.

Provided you do not use the Enable execution before Perl is relocated or Place in Bin Folder options (see below) once Citrus Perl has been relocated, you can move your own executables anywhere on storage available to the current machine by using the following practices:

MS Windows

In addition to the executable you must copy the entire contents of the CPerlDepExec folder and the appropriate scripts/execname.xpl maintaining the same relative paths at the new location.


In addition to the executable you must copy the appropriate scripts/execname.xpl maintaining the same relative paths at the new location.


For executables not packaged as a MacOSX .app, you must copy the appropriate scripts/execname.xpl maintaining the same relative paths at the new location. For a MacOSX .app bundle, just copy the entire bundle.


Resources used by your script must of course be located within the Perl tree or they will not be packaged when you create a new distribution. The location ../site/lib/auto/share/dist/somename is recommended. Within your script you can hard code the absolute path to these resources. The path will be changed when your distribution is relocated. Alternatively the function Citrus::RootPath() will always return the root path of your relocated Perl so you may also code paths relative to this root path.





Application Name

The application name is used on MacOSX and Windows for different purposes. It may contain letters, numbers and spaces.

On MacOSX, if creating a .app bundle, the application name is used to create application info available in Finder and to name the bundle itself.

On MS Windows the Application name is used in the application manifest. Spaces are replaced with periods for use in the assembly name member whilst the application name is used unchanged in the assembly description member.

Executable Name

On all platforms the executable name gives the actual executable file name. On MS Windows if the name does not end in '.exe' the Utilities Application will add it for you.

Source Script

Provide the path to a script to run from the executable. A copy of the script will be placed in ../pathtoperl/apps/scripts/scriptname.xpl or for a MacOSX bundle at ../Bundle

The script will be named after the executable. So, an exec named myprogexec.exe would have a script named myprogexec.xpl

Icon File

For MS Windows executables and MacOSX .app bundles you can add an inconfile of the type '.ico' or '.icns' depending on platform.

GUI Executable

For Windows this option makes the executable sub system 'Windows' so the executable will run without a visible console.

For MacOSX this option causes the executable to call 'SetFrontProcess' and bring any application window to the foreground. You almost certainly want it for a GUI application wrapped as a .app bundle.

Clear Perl Environment Variables

You can cause all Perl related environment variables to be removed before your Perl code executes by checking this option. For example any values for PERL5LIB or PERL5OPT will be deleted from the environment.

Allow Perl Interpreter Arguments

Normally, the executable wrapper does not recognise arguments to the Perl Interpreter but passes all arguments to the script in @ARGV. By checking this option you allow use of Perl Interpreter arguments by using the special argument list separator '--'. If you want to pass interpreter arguments you must use '--'

For example:

myexec -w -- -d --hello
-w is passed to the interpreter, -d and --hello are passed to script.

myexec -w -d --hello --
ALL params are passed to the interpreter. @ARGV is empty.

myexec -w -d --hello
NO params are passed to the interpreter. All arguments are in @ARGV.

Require Administrator

On MS Windows this will set the application manifest so that the executable will request administrative privileges before it can execute.

Place Executable in bin folder

By default, executables are placed in ../pathtoperl/apps. Check this option to place the executable in ../pathtoperl/bin.

Enable execution before Perl is relocated.

This is a special option that allows an executable to run before Perl has been relocated. This is the method used by the Citrus Utilities Application that allows it to run the install and relocation. Do not use this option unless you actually need to run before Perl is relocated. Perhaps your own custom install utility. An executable created with this option cannot be moved elsewhere.

Bundle as MacOSX App

On MacOSX you can choose to bundle a GUI app as a '.app' bundle. This allows you to associate icns (icon) files with the executable and provide a Mac friendly clickable app name and icon in Finder.

Overwrite Existing Executable

By default the application will not overwrite an existing executable with the same name. Click this option to force overwrite.

Contents Previous Next

Citrus Utilities Copyright © 2012 Mark Dootson