NAME

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

VERSION

This document describes Perl::Dist::WiX version 1.200_101.

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://test.invalid/',
);

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

INTERFACE

new

The new method creates a Perl::Dist::WiX object that describes a distribution of perl.

Each object is used to create a single distribution by calling run(), and then should be discarded.

Although there are over 60 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.

All attributes below can also be called as accessors on the object created.

There are six types of parameters that can be passed to new().

Types of distributions to build

This specifies the "highest" level of change in how the perl distribution is made - whether a .zip is requested, a .msi, a "thumb-drive portable" .zip, or a relocatable .msi or .zip.

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.

It defaults to true, unless portable() is true.

msm

The optional boolean msm param is used to indicate that a Windows Installer merge module (otherwise known as an msm file) should be created.

This defaults to true, unless portable() is true.

zip

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

This defaults to the value of portable().

portable

The optional portable parameter is used to determine whether a portable 'Perl-on-a-stick' distribution - one that is intended for distribution on a portable storage device - is built with this object.

If set to a true value, zip() must also be set to a true value, and msi() will be set to a false value.

This defaults to a false value.

relocatable

The optional relocatable parameter is used to determine whether the distribution is meant to be relocatable.

This defaults to a false value.

exe

The optional boolean exe param is unused at the moment.

Parameters that affect the build process.

These parameters affect the build process - whether modules are tested or not, how much information is given, what routines to run, etcetera.

force

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

This defaults to false.

forceperl

The optional forceperl parameter determines if perl and perl modules are tested upon installation. If this parameter is true, then testing is done only upon installed modules, not upon perl itself.

This defaults to false.

offline

The Perl::Dist::WiX 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 the offline parameter to new().

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

trace

The optional 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 a number between 2 and 5 will progressively print out more information about the build.

Numbers above 2 are only needed for debugging purposes.

Default is 1 if not set.

tasklist

The optional tasklist parameter specifies the list of routines that the object can do. The routines are object methods of Perl::Dist::WiX (or its subclasses) that will be executed in order, without parameters, and their task numbers (as used in Perl::Dist::WiX) will begin with 1 and increment in sequence.

Task routines should either return 1, or throw an exception.

The default task list for Perl::Dist::WiX is as shown below. Subclasses should provide their own list and insert their tasks in this list, rather than overriding routines shown above.

tasklist => [

	# Final initialization
	'final_initialization',

	# Install the core C toolchain
	'install_c_toolchain',

	# Install the Perl binary
	'install_perl',

	# Install the Perl toolchain
	'install_perl_toolchain',

	# Install additional Perl modules
	'install_cpan_upgrades',

	# Apply optional portability support
	'install_portable',

	# Apply optional relocation support
	'install_relocatable',

	# Remove waste and temporary files
	'remove_waste',

	# Regenerate file fragments
	'regenerate_fragments',

	# Find file ID's for relocation.
	'find_relocatable_fields',

	# Write out the merge module
	'write_merge_module',

	# Install the Win32 extras
	'install_win32_extras',

	# Create the distribution list
	'create_distribution_list',

	# Regenerate file fragments again.
	'regenerate_fragments',

	# Write out the distributions
	'write',
];

user_agent

The optional user_agent parameter stores the LWP::UserAgent object (or an object of a subclass of LWP::UserAgent) that Perl::Dist::WiX uses to download files.

The default depends on the user_agent_cache parameter.

user_agent_cache

The optional boolean user_agent_cache parameter specifies whether the default user_cache object is a LWP::UserAgent::WithCache (true) or a LWP::UserAgent object (false).

Defaults to a false value if not specified.

Parameters that describe the distribution to build.

These parameters specify the names/e-mails/etcetera used in making the distribution.

Some of these parameters are given no defaults by Perl::Dist::WiX, so either a subclass has to set these parameters, or they have to be specified.

app_id

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

app_name

The required app_name parameter provides the name of the distribution.

app_publisher

The required app_publisher parameter provides the publisher of the distribution.

app_publisher_url

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

It can be a string or a URI object.

app_ver_name

The optional app_ver_name parameter provides the name and version of the distribution.

The default value for this parameter is assembled from app_name and perl_version_human.

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.

bits

The optional bits parameter specifies whether the perl being built is for 32-bit (i386) or 64-bit (referred to as Intel64 / amd-x64) Windows

32-bit (i386) is the default.

build_number

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.

default_group_name

The optional name for the Start menu group that the distribution's installer installs its shortcuts to. Defaults to app_name if none is provided.

gcc_version

The optional gcc_version parameter specifies whether perl is being built using gcc 3.4.5 from the mingw32 project (by specifying a value of '3'), or using gcc 4.4.3 from the mingw64 project (by specifying a value of '4').

'3' (gcc 3.4.5) is the default, and is incompatible with bits => 64. '4' is compatible with both 32 and 64-bit, but is incompatible with perl_version => 589, 5100, or 5101.

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.

This defaults to false.

msi_exit_text

The optional msi_exit_text parameter is used to customize the text that the MSI shows on its last screen.

The default says: "Before you start using Perl, please read the README file."

msi_install_warning_text

Returns the text that the MSI needs to use when not able to relocate.

msi_run_readme_txt

Specifies whether to give the option to run a README.txt file when the installation is completed.

output_base_filename

The optional output_base_filename parameter specifies the filename (without extensions) that is used for the installer(s) being generated.

The default is based on app_id(), perl_version(), bits(), and the current date.

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.

perl_config_cf_by

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

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

If not defined, this is set to the username part of perl_config_cf_email.

perl_debug

The optional boolean perl_debug parameter is used to indicate that a debugging perl interpreter will be created.

This only applies to 5.12.0 and later as of yet.

perl_version

The perl_version parameter specifies what version of perl is downloaded and built. Legal values for this parameter are 'git', '589', '5100', '5101', '5120', and '5121' (for a version from perl5.git.perl.org, 5.8.9, 5.10.0, 5.10.1, and 5.12.1, respectively.)

This parameter defaults to '5101' if not specified.

sitename

The optional sitename parameter is used to generate the GUID's necessary during the process of building the distribution.

This defaults to the host part of app_publisher_url.

use_dll_relocation

The optional use_dll_relocation parameter specifies whether to use the C++ relocation dll that's being tested for relocating perl, or to call a Perl relocation script from the .msi's.

This parameter has no effect is the msi parameter is false, or if the relocatable parameter is false.

The default is false, so as to use the Perl relocation script instead.

Directories, files, and URLs used in building.

These parameters specify which directories and files are used when building a distribution.

At a minimum, image_dir is required, which specifies where Perl will be installed (by default, in the case where relocatable is true.) All other options have defaults, most of the time.

binary_root

The optional binary_root accessor is the URL (as a string, not including the filename) where the distribution will find its libraries to download.

Defaults to 'http://strawberryperl.com/package' unless offline is set, in which case it defaults to download_dir().

build_dir

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

Defaults to temp_dir . '\build', and must exist if given.

cpan

The optional 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. Strings will be coerced to URI objects.

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

If you are offline, it defaults to using a CPAN mirror at C:\minicpan\.

debug_stderr

The optional debug_stderr parameter is used to set the location of the file that STDERR is redirected to when the perl tarball and perl modules are built.

The default location is in debug.err in the output_dir.

debug_stdout

The optional debug_stdout parameter is used to set the location of the file that STDOUT is redirected to when the perl tarball and perl modules are built.

The default location is in debug.out in the output_dir.

download_dir

The optional download_dir parameter sets the location of the directory that packages of various types will be downloaded and cached to.

Defaults to temp_dir . '\download', and must exist if given.

fragment_dir

The optional subdirectory of temp_dir where the .wxs fragment files for the different portions of the distribution will be created.

Defaults to temp_dir . '\fragments', and needs to exist if given.

git_checkout

The optional git_checkout parameter is not used unless you specify that perl_version is 'git'. In that event, this parameter should contain a string pointing to the location of a checkout from http://perl5.git.perl.org/.

The default is 'C:\perl-git', if it exists.

git_location

The optional git_location parameter is not used unless you specify that perl_version is 'git'. In that event, this parameter should contain a string pointing to the location of the git.exe binary, as because a perl.exe file is in the same directory, it gets removed from the PATH during the execution of programs from Perl::Dist::WiX.

The default is 'C:\Program Files\Git\bin\git.exe', if it exists. Otherwise, the default is undef.

People on x64 systems should set this to 'C:\Program Files (x86)\Git\bin\git.exe' unless MSysGit is installed in a different location (or a 64-bit version becomes available).

This will be converted to a short name before execution, so this must NOT be on a partition that does not have them, unless the location does not have spaces.

image_dir

The required 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, and an attempt is made to prevent this from happening.

Perl::Dist::WiX distributions can only be installed to fixed paths as of yet, unless relocatable()|/relocatable is true.

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

license_dir

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

Defaults to image_dir . '\licenses', and needs to exist if given.

modules_dir

The optional modules_dir parameter sets the location of the directory that perl modules will be downloaded and cached to.

Defaults to download_dir . '\modules', and must exist if given.

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_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_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.

This defaults to not setting a URL.

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 filename if none is supplied here.

msi_product_icon

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

The default Windows Installer icon is used if none is specified here.

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.

There is no file linked if none is specified here.

output_dir

This optional output_dir parameter sets the location where the compiled installers and other files necessary to the build are written.

Defaults to temp_dir() . '\output', and must exist when given.

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 msi files.

The optional temp_dir parameter 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.

tempenv_dir

The processes that Perl::Dist::WiX executes sometimes need a place to put their temporary files, usually in $ENV{TEMP}.

The optional tempenv_dir parameter specifies the location to put those files.

This parameter defaults to a subdirectory of temp_dir() if not specified.

Using a merge module

Subclasses can start building a perl distribution from a merge module, instead of having to build perl from scratch.

This means that the distribution can:

1) update the version of Perl installed using the merge module.

2) be installed on top of another distribution using that merge module (or an earlier version of it).

The next 5 options specify the information required to use a merge module.

fileid_perl

The optional fileid_perl parameter helps the relocation find the perl executable.

If the merge module is being built, this is set by the install_relocatable method.

If the merge module is being used, it needs to be passed in to new().

fileid_relocation_pl

The optional fileid_relocation_pl parameter helps the relocation find the relocation script.

If the merge module is being built, this is set by the install_relocatable method.

If the merge module is being used, it needs to be passed in to new().

msm_code

The optional msm_code param is used to specify the product code for the merge module referred to in msm_to_use.

msm_to_use, msm_zip, and this parameter must either be all unset, or all set. They must be all set if initialize_using_msm is in the tasklist.

msm_to_use

The optional msm_to_use ...

It can be specified as a string, a Path::Class::File object, or a URI object.

msm_zip

The optional msm_zip refers to where the .zip version of Strawberry Perl that matches the merge module specified in msm_to_use

It can be a file:// URL if it's already downloaded.

It can be specified as a string, a Path::Class::File object, or a URI object.

Checkpointing builds.

To speed up debugging of a distribution build, that distribution can be checkpointed, and then restarted from that checkpoint.

These parameters control the checkpointing process.

checkpoint_after

The optional parameter checkpoint_after is an arrayref of task numbers. After each task in the list, Perl::Dist::WiX will stop and save a checkpoint.

[ 0 ] is the default, meaning that you do not wish to save a checkpoint anywhere.

checkpoint_before

The optional parameter checkpoint_before is given an integer to know when to load a checkpoint. Unlike the other parameters that deal with checkpointing, this is based on the task number that is GOING to execute, rather than the task number that just executed, so that if a checkpoint was saved after (for example) task 5, this parameter should be 6 in order to load the checkpoint and start on task 6.

0 is the default, meaning that you do not wish to load a checkpoint.

checkpoint_dir

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

Defaults to temp_dir . '\checkpoint', and must exist if given.

checkpoint_stop

The optional parameter checkpoint_stop stops execution after the specified task if no error has happened before then.

0 is the default, meaning that you do not wish to stop unless an error occurs.

run

The run method is the main method for the class.

It does a complete build of a product, spitting out an installer, by running each method named in the tasklist in order.

Returns true, or throws an exception on error.

This method may take an hour or more to run.

Methods used by `run` in the tasklist.

my $dist = Perl::Dist::WiX->new(
	tasklist => [
		'final_initialization',
		... 
	],
	...
);

These methods are used in the tasklist, along with other methods that are defined by Perl::Dist::WiX or its subclasses.

final_initialization

The final_initialization routine does the initialization that is required after the object representing a distribution has been created, but before files can be installed.

initialize_nomsm

The initialize_nomsm routine does the initialization that is required after final_initialization() has been called, but before files can be installed if msm() is 0.

initialize_using_msm

The initialize_using_msm routine does the initialization that is required after final_initialization() has been called, but before files can be installed if a merge module is to be used.

(see "Using a merge module" for more information.)

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_portable

The install_portable method is used by run() to install the perl modules to make Perl installable on a portable device.

install_relocatable

The install_relocatable method is used by run to install the perl script to make Perl relocatable when installed.

This routine must be run before "regenerate_fragments", so that the fragment created in this method is regenerated and the file ID can be found by "find_relocatable_fields" later.

find_relocatable_fields

The find_relocatable_fields method is used by run to find the property ID's required to make Perl relocatable when installed.

This routine must be run after regenerate_fragments().

install_win32_extras

The install_win32_extras method is used by run() to install the links and launchers into the Start menu.

remove_waste

The remove_waste method is used by run() to remove files that the distribution does not need to package.

regenerate_fragments

The regenerate_fragments method is used by run() to fully generate the object tree for file-containing fragments, which only contain a list of files until their regenerate() routines are run.

write

The write method is used by run() to compile the final installers for the distribution.

write_merge_module

The write_merge_module method is used by run() to compile the merge module for the distribution.

Package generation methods

These are the (private) routines that generate different types of packages and are called by the write() method when required.

_write_zip

$self->_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 database is not wanted (such as for "Portable Perl" type installations). It is called by write() when needed.

The .zip 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.

_write_msi

$self->_write_msi();

The _write_msi method is used to generate the compiled installer database. It creates the entire installation file tree, and then executes WiX to create the final executable.

This method is called by write().

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.

_write_msm

$self->_write_msm();

The _write_msm method is used to generate the compiled merge module used in the installer. It creates the entire installation file tree, and then executes WiX to create the merge module.

This method is called by write_merge_module(), and should only be called after all installation phases that install perl modules that should be in the .msm have been completed and all of the files for the merge module are in place.

The merge module 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.

_compile_wxs

Compiles a .wxs file (specified by $filename) into a .wixobj file (specified by $wixobj.) Both parameters are required.

This method is used by the _write_msi() and _write_msm() methods.

$self->_compile_wxs("Perl.wxs", "Perl.wixobj");

Accessors

$id = $dist->bin_candle();

Accessors will return a specified portion of the distribution state, rather than changing the distribution object's state.

msi_product_icon_id

Specifies the Id for the icon that is used in Add/Remove Programs for this MSI file.

feature_tree_object

Returns the Perl::Dist::WiX::FeatureTree object associated with this distribution.

bin_perl

bin_make

bin_pexports

bin_dlltool

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

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

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 for Perl::Dist::WiX.

Returns a directory as a Path::Class::Dir object or throws an exception on error.

pdw_class

Used in the templates for documentation purposes.

git_describe

The git_describe method returns the output of git describe on the directory pointed to by git_checkout.

perl_version_literal

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

For example, a Perl 5.8.9 distribution will return '5.008009'.

perl_version_human

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

This will be either 'git', '5.8.9', '5.10.0', '5.10.1', '5.12.0', or '5.12.1'.

distribution_version_human

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

distribution_version_file

The distribution_version_file method returns the "marketing" form of the distribution version, in such a way that it can be used in a file name.

output_date_string

Returns a stringified date in YYYYMMDD format for the use of other routines.

msi_ui_type

Returns the UI type that the MSI needs to use.

msi_platform_string

Returns the Platform attribute to the MSI's Package tag.

See http://wix.sourceforge.net/manual-wix3/wix_xsd_package.htm

msi_product_icon_id

Returns the product icon to use in the main template.

msi_product_id

Returns the Id for the MSI's <Product> tag.

See http://wix.sourceforge.net/manual-wix3/wix_xsd_product.htm

msm_product_id

Returns the Id for the <Product> tag for the MSI's merge module.

See http://wix.sourceforge.net/manual-wix3/wix_xsd_product.htm

msi_upgrade_code

Returns the Id for the MSI's <Upgrade> tag.

See http://wix.sourceforge.net/manual-wix3/wix_xsd_upgrade.htm

msm_package_id

Returns the Id for the MSM's <Package> tag.

See http://wix.sourceforge.net/manual-wix3/wix_xsd_package.htm

msm_package_id_property

Returns the Id for the MSM's <Package> tag, as the merge module would append it.

This is used in the main .wxs file.

msm_code_property

Returns the Id passed in as msm_code, as the merge module would append it.

This is used in the main .wxs file for subclasses.

msi_perl_version

Returns the Version attribute for the MSI's <Product> tag.

See http://wix.sourceforge.net/manual-wix3/wix_xsd_product.htm

perl_major_version

Gets the major version (the 8, 10, or 12 part of 5.8, 5.10, or 5.12) of the perl distribution being built.

msi_perl_major_version

Returns the major perl version so that upgrades that jump delete the site directory.

msi_relocation_commandline

Returns a command line to use in Main.wxs.tt for relocation purposes.

msm_relocation_commandline

Returns a command line to use in Merge-Module.wxs.tt for relocation purposes.

msi_relocation_commandline_files

Returns the files to use in Main.wxs.tt for relocation purposes.

This is overridden in subclasses, and creates an exception if not overridden.

msm_relocation_commandline_files

Returns the files to use in Merge-Module.wxs.tt for relocation purposes.

This is overridden in subclasses, and creates an exception if not overridden.

msi_relocation_ca

Returns which CA to use in Main.wxs.tt and Merge-Module.wxs.tt for relocation purposes.

msi_fileid_readme_txt

Returns the ID of the tag that installs a README.txt file.

perl_config_myuname

Returns the value to be used for perl -V:myuname, which is in this pattern:

Win32 app_id 5.10.0.1.beta_1 #1 Mon Jun 15 23:11:00 2009 i386

(the .beta_X is omitted if the beta_number accessor is not set.)

get_component_array

Returns the array of <Component Id>'s required.

See http://wix.sourceforge.net/manual-wix3/wix_xsd_component.htm, http://wix.sourceforge.net/manual-wix3/wix_xsd_componentref.htm

mk_debug

Used in the makefile.mk template for 5.11.5+ to activate building a debugging perl.

mk_gcc4

Used in the makefile.mk template for 5.12.0+ to activate building with gcc4.

mk_bits

Used in the makefile.mk template for 5.12.0+ to activate building 64 or 32-bit versions. (Actually, this turns off the fact that we're building a 64-bit version of perl when we want a 32-bit version on 64-bit processors)

mk_gcc4_dll

Used in the makefile.mk template for 5.12.0+ to activate using the correct helper dll for our gcc4 packs.

mk_extralibs

Used in the makefile.mk template for 5.12.0+ to activate using the correct extra library directory for our gcc4 packs.

patch_template

patch_template returns the Template object that is used to generate patched files.

fragment_exists

my $bool = $dist->fragment_exists('FragmentId');

Returns whether the fragment with the name given has been attached to this distribution.

get_fragment_object

my $fragment_tag = $dist->get_fragment_object('FragmentId');

Returns the WiX3::XML::Role::Fragment-using object that is attached to this distribution with the given name.

Returns undef if no such object found.

image_drive

The drive letter of the image directory. Retrieved from image_dir.

image_dir_url

Returns a string containing the image_dir as a file: URL.

image_dir_quotemeta

Returns a string containing the image_dir, with all backslashes converted to 2 backslashes.

get_output_files

Returns a list of output files created so far.

get_directory_tree

Retrieves the Perl::Dist::WiX::DirectoryTree2 object created to keep track of directories in this distribution.

get_merge_module_object

$self->get_merge_module_object('Perl');

Retrieves the Perl::Dist::WiX::Tag::MergeModule that has been added to the list that this distribution uses.

merge_module_exists

$self->get_merge_module_object('Perl');

Returns true or false as to whether the merge module named has been added to the list of merge modules included in this installer.

Other routines that your tasks (or users of the class) can use

add_merge_module

    $self->add_merge_module('Perl', $perl_merge_module);

Adds a Perl::Dist::WiX::Tag::MergeModule to the list of merge modules used in this distribution.

add_output_file

add_output_files

$self->add_output_files('information.html', 'README.txt');
$self->add_output_file('distribution.msi');

These two methods add files to the list of output files returned by get_output_files().

They also may create a Growl notification that is sent out locally if Growl::GNTP is installed. Growl for Windows (downloadable at http://www.growlforwindows.com/) can either display these notifications on the local machine, or forward them to another machine or device that can receive GNTP messages.

Growl notifications are only sent out for msi, msm, and zip files.

The application name sent out will be the class name used to create the distribution.

add_icon

    $self->add_icon(
	    name     => 'CPAN Client',
		filename => 'C:\strawberry\perl\bin\cpan.bat',
		icon_id  => 'I_cpan_bat_ico',
	);

This method adds a start menu icon to the installer that calls the file given as the filename parameter, and is named using the name parameter within the directory identified by the directory_id parameter, using the icon identified by the icon_id parameter.

If a description parameter is given, it is used as the description of the icon. If the directory_id parameter is not given, it defaults to 'D_App_Menu' (the application menu directory.)

icons_string

Calls Perl::Dist::WiX::IconArray->as_string() on the array of icons created for this distribution.

add_path

$self->add_path('perl', 'bin');

Adds a path entry that will be installed when the installer is executed.

get_path_string

my $ENV{PATH} = "$ENV{PATH};" . $dist->get_path_string();

Returns a string containing all the path entries that have been added, so that later portions of the installer generation can use the programs that have already been put in place.

add_env

$self->add_env('PATH', $self->image_dir()->subdir(qw(perl bin)), 1);
$self->add_env('TERM', 'dumb');

Adds the contents of $value to the environment variable $name (or appends to it, if $append is true) upon installation (by adding it to the Reg_Environment fragment.)

$name and $value are required.

add_file

$dist->add_file(
	source => $filename, 
	fragment => $fragment_name
);

Adds the file $filename to the fragment named by $fragment_name.

Both parameters are required, and the file and fragment must both exist.

insert_fragment

$self->insert_fragment($id, $files_obj, $overwritable);

Adds the list of files $files_obj (which is a File::List::Object) to the fragment named by $id. $overwritable defaults to false, and most be set to true if the files in this fragment can be overwritten by future fragments.

The fragment is created by this routine, so this can only be done once.

This MUST be done for each set of files to be installed in an MSI.

add_to_fragment

$dist->add_to_fragment($id, $files_obj);

Adds the list of files $files_obj (which is a File::List::Object) to the fragment named by $id.

The fragment must already exist.

File patching support

process_template

Loads the file template passed in as the first parameter, using this object, and returns it as a string.

Additional entries (beyond the one given that 'dist' is the Perl::Dist::WiX object) for the second parameter of Template->process are given as a list of pairs in the optional second parameter.

# Loads up the template for merge module docs.
$text = $self->process_template('Merge-Module.documentation.txt.tt');

patch_include_path

Returns an array reference containing a list of paths containing files that are used to replace or patch files in the distribution.

patch_pathlist

Returns the list of directories in patch_include_path as a File::PathList object.

patch_file

patch_file patches an individual file installed in the distribution using a file from the directories returned from "patch_pathlist".

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.32, Win32::Exe 0.13, Object::InsideOut 3.53, Perl::Dist 1.14, Process 0.26, Readonly 1.03, URI 1.35, and Win32 0.35.

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>

COPYRIGHT AND LICENSE

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.

To install Perl::Dist::WiX, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Perl::Dist::WiX

CPAN shell

perl -MCPAN -e shell
install Perl::Dist::WiX

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

DESCRIPTION

SYNOPSIS

INTERFACE

new

Types of distributions to build

msi

msm

zip

portable

relocatable

exe

Parameters that affect the build process.

force

forceperl

offline

trace

tasklist

user_agent

user_agent_cache

Parameters that describe the distribution to build.

app_id

app_name

app_publisher

app_publisher_url

app_ver_name

beta_number

bits

build_number

default_group_name

gcc_version

msi_debug

msi_exit_text

msi_install_warning_text

msi_run_readme_txt

output_base_filename

perl_config_cf_email

perl_config_cf_by

perl_debug

perl_version

sitename

use_dll_relocation

Directories, files, and URLs used in building.

binary_root

build_dir

cpan

debug_stderr

debug_stdout

download_dir

fragment_dir

git_checkout

git_location

image_dir

license_dir

modules_dir

msi_banner_side

msi_banner_top

msi_help_url

msi_license_file

msi_product_icon

msi_readme_file

output_dir

temp_dir

tempenv_dir

Using a merge module

fileid_perl

fileid_relocation_pl

msm_code

msm_to_use

msm_zip

Checkpointing builds.

checkpoint_after

checkpoint_before

checkpoint_dir

checkpoint_stop

run

Methods used by run in the tasklist.

final_initialization

initialize_nomsm

Methods used by `run` in the tasklist.