The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Perl-Dist-WiX-1.090_102
River stage one • 1 direct dependent • 1 total dependent
/ Perl::Dist::WiX

NAME

Perl::Dist::WiX - 4th generation Win32 Perl distribution builder

VERSION

This document describes Perl::Dist::WiX version 1.000.

DESCRIPTION

This package is the upgrade to Perl::Dist based on Windows Installer XML technology, instead of Inno Setup.

Perl distributions built with this module have the option of being created as Windows Installer databases (otherwise known as .msi files)

SYNOPSIS

        # Sets up a distribution with the following options
        my $distribution = Perl::Dist::WiX->new(
                msi               => 1,
                trace             => 1,
                build_number      => 1,
                cpan              => URI->new(('file://C|/minicpan/')),
                image_dir         => 'C:\myperl',
                download_dir      => 'C:\cpandl',
                output_dir        => 'C:\myperl_build',
                temp_dir          => 'C:\temp',
                app_id            => 'myperl',
                app_name          => 'My Perl',
                app_publisher     => 'My Perl Distribution Project',
                app_publisher_url => 'http:/myperl.invalid/',
                msi_directory_tree_additions => [ qw(
                  c\bin\program
                  perl\lib\Acme
                )],
        );

        # Creates the distribution
        $bb->run();

INTERFACE

new

The new method creates a new Perl Distribution build as an object.

Each object is used to create a single distribution, and then should be discarded.

Although there are about 30 potential constructor arguments that can be provided, most of them are automatically resolved and exist for overloading puposes only, or they revert to sensible defaults and generally never need to be modified.

This routine may take a few minutes to run.

An example of the most likely attributes that will be specified is in the SYNOPSIS.

Attributes that are required to be set are marked as (required) below. They may often be set by subclasses.

  • image_dir (required)

    Perl::Dist::WiX distributions can only be installed to fixed paths as of yet.

    To facilitate a correctly working CPAN setup, the files that will ultimately end up in the installer must also be assembled under the same path on the author's machine.

    The image_dir method specifies the location of the Perl install, both on the author's and end-user's host.

    Please note that this directory will be automatically deleted if it already exists at object creation time. Trying to build a Perl distribution on the SAME distribution can thus have devastating results.

  • temp_dir

    Perl::Dist::WiX needs a series of temporary directories while it is running the build, including places to cache downloaded files, somewhere to expand tarballs to build things, and somewhere to put debugging output and the final installer zip and exe files.

    The temp_dir param specifies the root path for where these temporary directories should be created.

    For convenience it is best to make these short paths with simple names, near the root.

    This parameter defaults to a subdirectory of $ENV{TEMP} if not specified.

  • force

    The force parameter determines if perl and perl modules are tested upon installation. If this parameter is true, then no testing is done.

  • trace

    The trace parameter sets the level of tracing that is output.

    Setting this parameter to 0 prints out only MAJOR stuff and errors.

    Setting this parameter to 2 or above will print out the level as the first thing on the line, and when an error occurs and an exception object is printed, a stack trace will be printed as well.

    Setting this parameter to 3 or above will print out the filename and line number after the trace level on those lines that require a trace level of 3 or above to print.

    Setting this parameter to 5 or above will print out the filename and line number on every line.

    Default is 1 if not set.

  • perl_version

    The perl_version parameter specifies what version of perl is downloaded and built. Legal values for this parameter are '589', '5100', and '5101' (for 5.8.9, 5.10.0, and 5.10.1, respectively.)

    This parameter defaults to '5101' if not specified.

  • cpan

    The cpan param provides a path to a CPAN or minicpan mirror that the installer can use to fetch any needed files during the build process.

    The param should be a URI object to the root of the CPAN repository, including trailing slash.

    If you are online and no cpan param is provided, the value will default to the http://cpan.strawberryperl.com repository as a convenience.

  • portable

    The optional boolean portable param is used to indicate that the distribution is intended for installation on a portable storable device. This creates a distribution in zip format.

  • zip

    The optional boolean zip param is used to indicate that a zip distribution package should be created.

  • msi

    The optional boolean msi param is used to indicate that a Windows Installer distribution package (otherwise known as an msi file) should be created.

  • exe

    The optional boolean exe param is unused at the moment.

  • app_id (required)

    The app_id parameter provides the base identifier of the distribution that is used in constructing filenames. This must be a legal Perl identifier (no spaces, for example) and is required.

  • app_name (required)

    The app_name parameter provides the name of the distribution. This is required.

  • app_publisher (required)

    The app_publisher parameter provides the publisher of the distribution.

  • app_publisher_url (required)

    The app_publisher_url parameter provides the URL of the publisher of the distribution.

  • default_group_name

    The name for the Start menu group this program installs its shortcuts to. Defaults to app_name if none is provided.

  • msi_debug

    The optional boolean msi_debug parameter is used to indicate that a debugging MSI (one that creates a log in $ENV{TEMP} upon execution in Windows Installer 4.0 or above) will be created if msi is also true.

  • build_number (required)

    The required integer build_number parameter is used to set the build number portion of the distribution's version number, and is used in constructing filenames.

  • beta_number

    The optional integer beta_number parameter is used to set the beta number portion of the distribution's version number (if this is a beta distribution), and is used in constructing filenames.

    It defaults to 0 if not set, which will construct distributions without a beta number.

  • msi_license_file

    The optional msi_license_file parameter specifies the location of an .rtf or .txt file to be displayed at the point where the MSI asks you to accept a license.

    Perl::Dist::WiX provides a default one if none is supplied here.

  • msi_banner_top

    The optional msi_banner_top parameter specifies the location of a 493x58 .bmp file that is used on the top of most of the dialogs in the MSI file.

    WiX will use its default if no file is supplied here.

  • msi_banner_side

    The optional msi_banner_side parameter specifies the location of a 493x312 .bmp file that is used in the introductory dialog in the MSI file.

    WiX will use its default if no file is supplied here.

  • msi_help_url

    The optional msi_help_url parameter specifies the URL that Add/Remove Programs directs you to for support when you click the "Click here for support information." text.

  • msi_readme_file

    The optional msi_readme_file parameter specifies a .txt or .rtf file or a URL (TODO: check) that is linked in Add/Remove Programs in the "Click here for support information." text.

  • msi_product_icon

    The optional msi_product_icon parameter specifies the icon that is used in Add/Remove Programs for this MSI file.

  • msi_directory_tree_additions

    The optional msi_directory_tree_additions parameter is a reference to an array of directories under image_dir (i.e. perl\lib\Module, as opposed to C:\distribution\perl\lib\module) that need to be in the initial directory tree because they are used by more than one fragment.

    If upon running the distribution module, you see LGHT0091 or LGHT0130 errors at the end that refer to directories, add the applicable directories to this parameter.

  • perl_config_cf_email

    The optional perl_config_cf_email parameter specifies the e-mail of the person building the perl distribution defined by this object.

    It is compiled into the perl binary as the cf_email option accessible through perl -V:cf_email.

    The username (the part before the at sign) of this parameter also sets the cf_by option.

    If not defined, this is set to anonymous@unknown.builder.invalid.

The new constructor returns a Perl::Dist::WiX object, which you should then call run on to generate the distribution.

Accessors

        $id = $dist->bin_candle;

Accessors will return a specified portion of the distribution state.

If it can also be set as a parameter to new, it is marked as (also new parameter) below.

binary_root

(also new parameter)

The binary_root accessor returns the URL (as a string, not including the filename) where the distribution will be uploaded.

Defaults to 'http://strawberryperl.com/package'.

modules_dir

(also new parameter)

The directory where the modules for the distribution will be downloaded to.

Defaults to download_dir . '\modules'.

license_dir

(also new parameter)

The subdirectory of image_dir where the licenses for the different portions of the distribution will be copied to.

Defaults to image_dir . '\licenses'.

build_dir

(also new parameter)

The directory where the source files for the distribution will be extracted and built from.

Defaults to temp_dir . '\build'.

checkpoint_dir

(also new parameter)

The directory where Perl::Dist::WiX will store its checkpoints.

Defaults to temp_dir . '\checkpoint'.

bin_perl, bin_make, bin_pexports, bin_dlltool

The location of perl.exe, dmake.exe, pexports.exe, and dlltool.exe.

These only are available (not undef) once the appropriate packages are installed.

env_path

An arrayref storing the different directories under image_dir that need to be added to the PATH.

debug_stdout, debug_stderr

The files where STDOUT and STDERR is redirected to to receive the output of make and perl.

Defaults to output_dir . '\debug.out' and output_dir . '\debug.err'

perl_version_corelist

A hash containing the versions of the core modules in the version of perl being distributed. Retrieved from Module::CoreList.

output_file

The list of distributions created as an array reference.

filters

Provides an array reference of files and directories that will not be installed.

Initialized in new.

dist_dir

Provides a shortcut to the location of the shared files directory.

Returns a directory as a string or throws an exception on error.

wix_dist_dir

Provides a shortcut to the location of the shared files directory.

Returns a directory as a string or throws an exception on error.

offline

The Perl::Dist module has limited ability to build offline, if all packages have already been downloaded and cached.

The connectedness of the Perl::Dist object is checked automatically be default using LWP::Online. It can be overidden by providing an offline param to the constructor.

The offline accessor returns true if no connection to "the internet" is available and the object will run in offline mode, or false otherwise.

download_dir

(also new parameter)

The download_dir accessor returns the path to the directory that packages of various types will be downloaded and cached to.

An explicit value can be provided via a download_dir param to the constructor. Otherwise the value is derived from temp_dir.

image_dir

(also new parameter)

The image_dir accessor returns the path to the built distribution image. That is, the directory in which the build C/Perl code and modules will be installed on the build server.

At the present time, this is also the path to which Perl will be installed on the user's machine via the source_dir accessor, which is an alias to the Perl::Dist::WiX::Installer method source_dir. (although theoretically they can be different, this is likely to break the user's Perl install)

perl_version

The perl_version accessor returns the shorthand perl version as a string (consisting of the three-part version with dots removed).

Thus Perl 5.8.9 will be "589" and Perl 5.10.0 will return "5100".

perl_version_literal

The perl_version_literal method returns the literal numeric Perl version for the distribution.

For Perl 5.8.8 this will be '5.008008', Perl 5.8.9 will be '5.008009', and for Perl 5.10.0 this will be '5.010000'.

perl_version_human

The perl_version_human method returns the "marketing" form of the Perl version.

This will be either '5.8.9', '5.10.0', or '5.10.1'.

distribution_version_human

The distribution_version_human method returns the "marketing" form of the distribution version.

run

The run method is the main method for the class.

It does a complete build of a product, spitting out an installer.

Returns true, or throws an exception on error.

This method may take an hour or more to run.

Routines used by run

install_custom

The install_custom method is an empty install stub provided to allow sub-classed distributions to add vastly different additional packages on top of Strawberry Perl.

For example, this class is used by the Parrot distribution builder (which needs to sit on a full Strawberry install).

Notably, the install_custom method comes AFTER remove_waste, so that the file deletion logic in remove_waste won't accidentally delete files that may result in a vastly more damaging effect on the custom software.

Returns true, or throws an error on exception.

install_c_toolchain

The install_c_toolchain method is used by run to install various binary packages to provide a working C development environment.

By default, the C toolchain consists of dmake, gcc (C/C++), binutils, pexports, the mingw runtime environment, and the win32api C package.

Although dmake is the "standard" make for Perl::Dist distributions, it will also install the mingw version of GNU make for use with those modules that require it.

install_c_libraries

The install_c_libraries method is an empty install stub provided to allow sub-classed distributions to add vastly different additional packages on top of Strawberry Perl.

Returns true, or throws an error on exception.

write_zip

The write_zip method is used to generate a standalone .zip file containing the entire distribution, for situations in which a full installer executable is not wanted (such as for "Portable Perl" type installations).

The executable file is written to the output directory, and the location of the file is printed to STDOUT.

Returns true or throws an exception or error.

DIAGNOSTICS

See Perl::Dist::WiX::Diagnostics for a list of exceptions that this module can throw.

DEPENDENCIES

Perl 5.8.1 is the mimimum version of perl that this module will run on.

Other modules that this module depends on are a working version of Alien::WiX, Data::Dump::Streamer 2.08, Data::UUID 1.149, Devel::StackTrace 1.20, Exception::Class 1.22, File::ShareDir 1.00, IO::String 1.08, List::MoreUtils 0.07, Module::CoreList 2.17, Object::InsideOut 3.53, Perl::Dist 1.14, Process 0.26, Readonly 1.03, URI 1.35, and Win32 0.35.

TODO

  1. Create a distribution for handling the XML-generating parts of Perl::Dist::WiX and depend on it (1.100? 2.000?)

  2. Have an option to have WiX installed non-core modules install in a 'vendor path' (1.010)

BUGS AND LIMITATIONS (SUPPORT)

Bugs should be reported via:

1) The CPAN bug tracker at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Perl-Dist-WiX if you have an account there.

2) Email to <bug-Perl-Dist-WiX@rt.cpan.org> if you do not.

For other issues, contact the topmost author.

AUTHORS

Curtis Jewell <csjewell@cpan.org>

Adam Kennedy <adamk@cpan.org>

SEE ALSO

Perl::Dist, Perl::Dist::Inno, http://ali.as/, http://csjewell.comyr.com/perl/

COPYRIGHT AND LICENSE

Copyright 2009 Curtis Jewell.

Copyright 2008 - 2009 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.