NAME
Perl::Dist::WiX - 4th generation Win32 Perl distribution builder
VERSION
This document describes Perl::Dist::WiX version 1.102001.
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 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.
All attributes below can also be called as accessors on the object created.
app_id (required)
The 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) 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.
app_ver_name
The app_ver_name parameter provides the name and version of the distribution.
This is not required, and is assembled from app_name and perl_version_human if not given.
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.
binary_root
The 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 the empty string.
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_dir
The directory where the source files for the distribution will be extracted and built from.
Defaults to temp_dir . '\build', and must exist if given.
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.
checkpoint_after
checkpoint_after is given 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
checkpoint_before is given an integer to know when to load a checkpoint. Unlike the other parameters, 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 stop unless an error occurs.
checkpoint_dir
The directory where Perl::Dist::WiX will store its checkpoints.
Defaults to temp_dir . '\checkpoint', and must exist if given.
checkpoint_stop
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.
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.
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.
default_group_name
The name for the Start menu group that the distribution's installer installs its shortcuts to. Defaults to app_name if none is provided.
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.
exe
The optional boolean exe param is unused at the moment.
force
The force parameter determines if perl and perl modules are tested upon installation. If this parameter is true, then no testing is done.
forceperl
The force 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.
fragment_dir
The 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.
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.
git_checkout
The 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 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 (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, and an attempt is made to prevent this from happening.
license_dir
The 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
The optional boolean msi param is used to indicate that a Windows Installer distribution package (otherwise known as an msi file) should be created.
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_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.
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_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_product_icon
The optional msi_product_icon parameter specifies the icon that is used in Add/Remove Programs for this MSI file.
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.
msm
The optional boolean msi param is used to indicate that a Windows Installer distribution package (otherwise known as an msi file) should be created.
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.
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.
output_dir
This is the location where the compiled installers and other files neccessary to the build are written.
Defaults to temp_dir . '\output', and must exist when given.
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_version
The perl_version parameter specifies what version of perl is downloaded and built. Legal values for this parameter are 'git', '589', '5100', and '5101' (for a version from perl5.git.perl.org, 5.8.9, 5.10.0, and 5.10.1, respectively.)
This parameter defaults to '5101' if not specified.
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.
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.
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, and their task numbers (as used below) 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.
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 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.
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.
user_agent
The 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 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 true value if not specified.
zip
The optional boolean zip param is used to indicate that a zip distribution package should be created.
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.
fragment_dir
The location where this object will write the information for WiX to process to create the MSI. A default is provided if this is not specified.
directories
Returns the Perl::Dist::WiX::DirectoryTree object associated with this distribution. Created by "new"
fragments
Returns a hashref containing the objects subclassed from Perl::Dist::WiX::Base::Fragment associated with this distribution. Created as the distribution's "run" routine progresses.
msi_feature_tree
Returns the parameter of the same name passed in from "new". Unused as of yet.
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 location 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 string or throws an exception on error.
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 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 'git', '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.
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 MSI's <Package> tag.
See http://wix.sourceforge.net/manual-wix3/wix_xsd_package.htm
msm_package_id_property
Returns the Id for the MSI's <Package> tag, as the merge module would append it.
This is used in the main object
msi_perl_version
Returns the Version attribute for the MSI's <Product> tag.
See http://wix.sourceforge.net/manual-wix3/wix_xsd_product.htm
msi_perl_major_version
Returns the major perl version so that upgrades that jump delete the site directory.
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 ommitted 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
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
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.
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_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.
_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.
add_icon
TODO
add_path
TODO
get_path_string
TODO
_compile_wxs($filename, $wixobj)
Compiles a .wxs file (specified by $filename) into a .wixobj file (specified by $wixobj.) Both parameters are required.
$self = $self->_compile_wxs("Perl.wxs", "Perl.wixobj");_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, and should only be called after all installation phases have been completed and all of the files for the distribution are in place.
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.
add_env($name, $value [, $append])
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({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($id, $files_ref)
Adds the list of files $files_ref to the fragment named by $id.
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($id, $files_ref)
Adds the list of files $files_ref to the fragment named by $id.
The fragment must already exist.
as_string
Loads the file template passed in as the parameter, using this object, and returns it as a string.
# Loads up the merge module template.
$wxs = $self->as_string('Merge-Module.wxs.tt');
# Loads up the main template
$wxs = $self->as_string('Main.wxs.tt');File Patching support
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_template
patch_template returns the Template object that is used to generate patched files.
patch_file
patch_file patches an individual file installed in the distribution using a file from the directories returned from patch_pathlist.
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.
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
Add the ability to build in a 32 or 64 bit toolchain using gcc 4.x.x.
Make the perl distribution relocatable.
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 - 2010 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.