Perl::Dist::WiX - 4th generation Win32 Perl distribution builder
This document describes Perl::Dist::WiX version 1.500002.
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)
# 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();
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().
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.
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
It defaults to true, unless portable() is true.
The optional boolean msm param is used to indicate that a Windows Installer merge module (otherwise known as an msm file) should be created.
msm
This defaults to true, unless portable() is true.
The optional boolean zip param is used to indicate that a zip distribution package should be created.
zip
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.
portable
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.
The optional relocatable parameter is used to determine whether the distribution is meant to be relocatable.
relocatable
The optional boolean exe param is unused at the moment.
exe
These parameters affect the build process - whether modules are tested or not, how much information is given, what routines to run, etcetera.
The optional force parameter determines if perl and perl modules are tested upon installation. If this parameter is true, then no testing is done.
force
This defaults to false.
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.
forceperl
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().
offline
The offline accessor returns true if no connection to "the internet" is available and the object will run in offline mode, or false otherwise.
The optional trace parameter sets the level of tracing that is output.
trace
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.
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.
tasklist
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', # Check for missing files. 'verify_msi_file_contents', # 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', # Check for missing files. 'verify_msi_file_contents', # Regenerate file fragments again. 'regenerate_fragments', # Write out the distributions 'write', ];
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.
user_agent
The default creates an user_agent_cache parameter.
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.
Perl::Dist::WiX
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_id
The required app_name parameter provides the name of the distribution.
app_name
The required app_publisher parameter provides the publisher of the distribution.
app_publisher
The required app_publisher_url parameter provides the URL of the publisher of the distribution.
app_publisher_url
It can be a string or a URI object.
The optional app_ver_name parameter provides the name and version of the distribution.
app_ver_name
The default value for this parameter is assembled from app_name and perl_version_human.
perl_version_human
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.
beta_number
It defaults to 0 if not set, which will construct distributions without a beta number.
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
bits
32-bit (i386) is the default.
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.
build_number
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.
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').
gcc_version
'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 => 5100 5101.
bits => 64
perl_version => 5100 5101
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_debug
The optional msi_exit_text parameter is used to customize the text that the MSI shows on its last screen.
msi_exit_text
The default says: "Before you start using Perl, please read the README file."
Returns the text that the MSI needs to use when not able to relocate.
Specifies whether to give the option to run a README.txt file when the installation is completed.
The optional output_base_filename parameter specifies the filename (without extensions) that is used for the installer(s) being generated.
output_base_filename
The default is based on app_id(), perl_version(), bits(), and the current date.
app_id()
perl_version()
bits()
The optional perl_config_cf_email parameter specifies the e-mail of the person building the perl distribution defined by this object.
perl_config_cf_email
It is compiled into the perl binary as the cf_email option accessible through perl -V:cf_email.
cf_email
perl -V:cf_email
The username (the part before the at sign) of this parameter also sets the cf_by option.
cf_by
If not defined, this is set to anonymous@unknown.builder.invalid.
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.
perl -V:cf_by
If not defined, this is set to the username part of perl_config_cf_email.
The optional boolean perl_debug parameter is used to indicate that a debugging perl interpreter will be created.
perl_debug
This only applies to 5.12.0 and later as of yet.
The perl_version parameter specifies what version of perl is downloaded and built. Legal values for this parameter are 'git', '5100', '5101', '5120', and '5121' (for a version from perl5.git.perl.org, 5.10.0, 5.10.1, and 5.12.1, respectively.)
perl_version
This parameter defaults to '5101' if not specified.
The optional sitename parameter is used to generate the GUID's necessary during the process of building the distribution.
sitename
This defaults to the host part of app_publisher_url.
The optional boolean smoketest parameter is used to indicate that a 'smoketest' marked perl interpreter will be created.
smoketest
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.
use_dll_relocation
This parameter has no effect is the msi parameter is false, or if the relocatable parameter is false.
If this variable is false, the Perl relocation script is used instead. (The default is true.)
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.
The optional binary_root accessor is the URL (as a string, not including the filename) where the distribution will find its libraries to download.
binary_root
Defaults to 'http://strawberryperl.com/package' unless offline is set, in which case it defaults to download_dir().
download_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.
temp_dir
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.
cpan
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\.
C:\minicpan\
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.
debug_stderr
The default location is in debug.err in the output_dir.
debug.err
output_dir
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.
debug_stdout
The default location is in debug.out in the output_dir.
debug.out
The optional download_dir parameter sets the location of the directory that packages of various types will be downloaded and cached to.
download_dir
Defaults to temp_dir . '\download', and must exist if given.
temp_dir . '\download'
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.
temp_dir . '\fragments'
The optional git_checkout parameter is not used unless you specify that perl_version is a plugin that implements building from a git checkout. In that event, this parameter should contain a string pointing to the location of a checkout from http://perl5.git.perl.org/.
git_checkout
The default is 'C:\perl-git', if it exists.
'C:\perl-git'
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.
git_location
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).
'C:\Program Files (x86)\Git\bin\git.exe'
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.
The required image_dir method specifies the location of the Perl install, both on the author's and end-user's host.
image_dir
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.
relocatable()|/relocatable
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.
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.
image_dir . '\licenses'
The optional modules_dir parameter sets the location of the directory that perl modules will be downloaded and cached to.
modules_dir
Defaults to download_dir . '\modules', and must exist if given.
download_dir . '\modules'
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.
msi_banner_side
WiX will use its default if no file is supplied here.
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.
msi_banner_top
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_help_url
This defaults to not setting a URL.
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.
msi_license_file
Perl::Dist::WiX provides a default filename if none is supplied here.
The optional msi_product_icon parameter specifies the icon that is used in Add/Remove Programs for this MSI file.
msi_product_icon
The default Windows Installer icon is used if none is specified here.
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_readme_file
There is no file linked if none is specified here.
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() . '\output'
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.
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.
tempenv_dir
This parameter defaults to a subdirectory of temp_dir() if not specified.
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.
The optional fileid_perl parameter helps the relocation find the perl executable.
fileid_perl
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().
TODO
The optional fileid_relocation_pl parameter helps the relocation find the relocation script.
fileid_relocation_pl
The optional msm_code parameter is used to specify the product code for the merge module referred to in msm_to_use.
msm_code
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_zip
initialize_using_msm
The optional msm_to_use parameter is the location of a merge module to use when linking the .msi.
It can be specified as a string, a Path::Class::File object, or a URI object.
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.
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.
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.
checkpoint_after
[ 0 ] is the default, meaning that you do not wish to save a checkpoint anywhere.
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.
checkpoint_before
0 is the default, meaning that you do not wish to load a checkpoint.
The optional directory where Perl::Dist::WiX will store its checkpoints.
Defaults to temp_dir . '\checkpoint', and must exist if given.
The optional parameter checkpoint_stop stops execution after the specified task if no error has happened before then.
checkpoint_stop
0 is the default, meaning that you do not wish to stop unless an error occurs.
The run method is the main method for the class.
run
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.
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.
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.
final_initialization
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_nomsm
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.)
The install_c_toolchain method is used by run() to install various binary packages to provide a working C development environment.
install_c_toolchain
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.
The install_portable method is used by run() to install the perl modules to make Perl installable on a portable device.
install_portable
The install_relocatable method is used by run to install the perl script to make Perl relocatable when installed.
install_relocatable
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.
The find_relocatable_fields method is used by run to find the property ID's required to make Perl relocatable when installed.
find_relocatable_fields
This routine must be run after regenerate_fragments().
The install_win32_extras method is used by run() to install the links and launchers into the Start menu.
install_win32_extras
The remove_waste method is used by run() to remove files that the distribution does not need to package.
remove_waste
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.
regenerate_fragments
regenerate()
This method is used by run() to verify that all the files that are supposed to be in the .msi or .msm are actually in it. ('supposed to be' is defined as 'the files would be in the .zip at this point'.)
This method does not verify anything (start menu options, etc.) that does not go in the image_dir()
The write method is used by run() to compile the final installers for the distribution.
write
The write_merge_module method is used by run() to compile the merge module for the distribution.
write_merge_module
These are the (private) routines that generate different types of packages and are called by the write() method when required.
$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.
_write_zip
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.
$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.
_write_msi
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.
$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.
_write_msm
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.
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");
$id = $dist->bin_candle();
Accessors will return a specified portion of the distribution state, rather than changing the distribution object's state.
Specifies the Id for the icon that is used in Add/Remove Programs for this MSI file.
Returns the Perl::Dist::WiX::FeatureTree object associated with this distribution.
The locations of perl.exe, dmake.exe, pexports.exe, and dlltool.exe.
These only are available (not undef) once the appropriate packages are installed.
Provides a shortcut to the location of the shared files directory.
Returns a directory as a string or throws an exception on error.
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.
Used in the templates for documentation purposes.
The perl_version_literal method returns the literal numeric Perl version for the distribution.
perl_version_literal
For example, a Perl 5.10.1 distribution will return '5.010001'.
The perl_version_human method returns the "marketing" form of the Perl version.
This will be either 'git', or a string along the lines of '5.10.0'.
The distribution_version_human method returns the "marketing" form of the distribution version.
distribution_version_human
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.
distribution_version_file
Returns a stringified date in YYYYMMDD format for the use of other routines.
Returns the UI type that the MSI needs to use.
Returns the Platform attribute to the MSI's Package tag.
See http://wix.sourceforge.net/manual-wix3/wix_xsd_package.htm
Returns the product icon to use in the main template.
Returns the Id for the MSI's <Product> tag.
See http://wix.sourceforge.net/manual-wix3/wix_xsd_product.htm
Returns the Id for the <Product> tag for the MSI's merge module.
Returns the Id for the MSI's <Upgrade> tag.
See http://wix.sourceforge.net/manual-wix3/wix_xsd_upgrade.htm
Returns the Id for the MSM's <Package> tag.
Returns the Id for the MSM's <Package> tag, as the merge module would append it.
This is used in the main .wxs file.
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.
Returns the Version attribute for the MSI's <Product> tag.
Gets the major version (the 10, or 12 part of 5.10, or 5.12) of the perl distribution being built.
Returns the major perl version so that upgrades that jump delete the site directory.
Returns a command line to use in Main.wxs.tt for relocation purposes.
Returns a command line to use in Merge-Module.wxs.tt for relocation purposes.
Returns the files to use in Main.wxs.tt for relocation purposes.
This is overridden in subclasses, and creates an exception if not overridden.
Returns the files to use in Merge-Module.wxs.tt for relocation purposes.
Returns which CA to use in Main.wxs.tt and Merge-Module.wxs.tt for relocation purposes.
Returns the ID of the tag that installs a README.txt file.
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.)
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
Used in the makefile.mk template for 5.12.0+ to activate building a debugging perl.
Used in the makefile.mk template for 5.12.0+ to activate building with gcc4.
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)
Used in the makefile.mk template for 5.12.0+ to activate using the correct helper dll for our gcc4 packs.
Used in the makefile.mk template for 5.12.0+ to activate using the correct extra library directory for our gcc4 packs.
patch_template returns the Template object that is used to generate patched files.
patch_template
my $bool = $dist->fragment_exists('FragmentId');
Returns whether the fragment with the name given has been attached to this distribution.
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.
The drive letter of the image directory. Retrieved from image_dir.
Returns a string containing the image_dir as a file: URL.
Returns a string containing the image_dir, with all backslashes converted to 2 backslashes.
Returns a list of output files created so far.
Retrieves the Perl::Dist::WiX::DirectoryTree object created to keep track of directories in this distribution.
$self->get_merge_module_object('Perl');
Retrieves the Perl::Dist::WiX::Tag::MergeModule that has been added to the list that this distribution uses.
Returns true or false as to whether the merge module named has been added to the list of merge modules included in this installer.
$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.
$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.
$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.
filename
name
directory_id
icon_id
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.)
description
Calls Perl::Dist::WiX::IconArray->as_string() on the array of icons created for this distribution.
$self->add_path('perl', 'bin');
Adds a path entry that will be installed when the installer is executed.
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.
$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.
$dist->add_file( source => $filename, fragment => $fragment_name );
Adds the file $filename to the fragment named by $fragment_name.
$filename
$fragment_name
Both parameters are required, and the file and fragment must both exist.
$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.
$files_obj
$id
$overwritable
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.
$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.
See Perl::Dist::WiX::Diagnostics for a list of exceptions that this module can throw.
Perl 5.10.0 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 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.
Curtis Jewell <csjewell@cpan.org>
Adam Kennedy <adamk@cpan.org>
Perl::Dist, Perl::Dist::Inno, http://ali.as/, http://csjewell.comyr.com/perl/
Copyright 2009 - 2011 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.
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.