Perl::Dist::Inno - 3rd Generation Distribution Builder using Inno Setup
Creating a custom distribution
package My::Perl::Dist; use strict; use base 'Perl::Dist::Strawberry'; 1;
Building that distribution...
> perldist --cpan "file://c|/minicpan/" Strawberry
Perl::Dist::Inno is a Win32 Perl distribution builder that targets the Inno Setup 5 installer creation program.
It provides a rich set of functionality that allows a distribution developer to specify either Perl 5.8.8 or Perl 5.10.0, specify additional C libraries and CPAN modules to be installed, and then set start menu entries to websites and programs as needed.
A distribution directory and a matching .iss script is generated, which is then handed off to Inno Setup 5 to create the final distribution .exe installer.
Alternatively, Perl::Dist::Inno can generate a .zip file for the distribution without the installer.
Because the API for Perl::Dist::Inno is extremely rich and fairly complex (and a moving target) the documentation is unfortunately a bit less complete than it should be.
As parts of the API solidify I hope to document them better.
The Perl::Dist::Inno API is separated into 2 layers, and a series of objects.
Perl::Dist::Inno::Script provides the direct mapping to the Inno Setup 5 .iss script, and has no logical understand of Perl Distribution.
It stores the values that will ultimately be written into the .iss files as attributes, and contains a series of collections of Perl::Dist::Inno::File, Perl::Dist::Inno::Registry and L>Perl::Dist::Inno::Icon> objects, which map directly to entries in the .iss script's [Files], [Icons] and [Registry] sections.
To the extent that it does interact with actual distributions, it is only to the extent of validating some directories exist, and triggering the actual execution of the Inno Setup 5 compiler.
Perl::Dist::Inno (this class) is a sub-class of Perl::Dist::Inno::Script and represents the layer at which the understanding of the Perl distribution itself is implemented.
Perl::Dist::Asset and its various subclasses provides the internal representation of the logical elements of a Perl distribution.
These assets are mostly transient and are destroyed once the asset has been added to the distribution (this may change).
In the process of adding the asset to the distribution, various files may be created and objects added to the script object that will result in .iss keys being created where the installer builder needs to know about that asset explicitly.
Perl::Dist::Inno itself provides both many levels of abstraction with sensible default implementations of high level concept methods, as well as multiple levels of submethods.
Strong separation of concerns in this manner allows people creating distribution sub-classes to add hooks to the build process in many places, for maximum customisability.
The main Perl::Dist::Inno run method implements the basic flow for the creation of a Perl distribution. The order is rougly as follows:
Rather than building directly on top of Perl::Dist::Inno, it is probably better to build on top of a particular distribution, probably Strawberry.
For more information, see the Perl::Dist::Strawberry documentation which details how to sub-class the distribution.
The new method creates a new Perl Distribution build as an object.
Each object is used to create a single distribution, and then should be discarded.
Although there are about 30 potential constructor arguments that can be provided, most of them are automatically resolved and exist for overloading puposes only, or they revert to sensible default and generally never need to be modified.
The following is an example of the most likely attributes that will be specified.
my $build = Perl::Dist::Inno->new( image_dir => 'C:\vanilla', temp_dir => 'C:\tmp\vp', cpan => 'file://C|/minicpan/', );
Perl::Dist::Inno distributions can only be installed to fixed paths.
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.
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 devestating results.
Perl::Dist::Inno needs a series of temporary directories while it is running the build, including places to cache downloaded files, somewhere to expand tarballs to build things, and somewhere to put debugging output and the final installer zip and exe files.
The temp_dir param specifies the root path for where these temporary directories should be created.
temp_dir
For convenience it is best to make these short paths with simple names, near the root.
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.
cpan
The param should be a URI object to the root of the CPAN repository, including trailing newline.
If you are online and no cpan param is provided, the value will default to the http://cpan.strawberryperl.com repository as a convenience.
The optional boolean portable param is used to indicate that the distribution is intended for installation on a portable storable device.
portable
The optional boolean zip param is used to indicate that a zip distribution package should be created.
zip
The optional boolean exe param is used to indicate that an InnoSetup executable installer should be created.
exe
The new constructor returns a Perl::Dist object, which you should then call run on to generate the distribution.
new
run
The Perl::Dist module has limited ability to build offline, if all packages have already been downloaded and cached.
The connectedness of the Perl::Dist object is checked automatically be default using LWP::Online. It can be overidden by providing an offline param to the constructor.
The offline accessor returns true if no connection to "the internet" is available and the object will run in offline mode, or false otherwise.
offline
The download_dir accessor returns the path to the directory that packages of various types will be downloaded and cached to.
download_dir
An explicit value can be provided via a download_dir param to the constructor. Otherwise the value is derived from temp_dir.
The image_dir accessor returns the path to the built distribution image. That is, the directory in which the build C/Perl code and modules will be installed on the build server.
At the present time, this is also the path to which Perl will be installed on the user's machine via the source_dir accessor, which is an alias to the Perl::Dist::Inno::Script method source_dir. (although theoretically they can be different, this is likely to break the user's Perl install)
source_dir
The perl_version accessor returns the shorthand perl version as a string (consisting of the three-part version with dots removed).
perl_version
Thus Perl 5.8.8 will be "588" and Perl 5.10.0 will return "5100".
The perl_version_literal method returns the literal numeric Perl version for the distribution.
perl_version_literal
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'.
The perl_version_human method returns the "marketing" form of the Perl version.
perl_version_human
This will be either '5.8.8', '5.8.9' or '5.10.0'.
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.
The install_custom method is an empty install stub provided to allow sub-classed distributions to add vastly different additional packages on top of Strawberry Perl.
install_custom
For example, this class is used by the Parrot distribution builder (which needs to sit on a full Strawberry install).
Notably, the install_custom method AFTER remove_waste, so that the file deletion logic in remove_waste won't accidntally delete files that may result in a vastly more damaging effect on the custom software.
remove_waste
Returns true, or throws an error on exception.
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...
TO BE CONTINUED
The install_perl_5100 method provides a simplified way to install Perl 5.10.0 into the distribution.
install_perl_5100
It takes care of calling install_perl_5100_bin with the standard params, and then calls install_perl_5100_toolchain to set up the Perl 5.10.0 CPAN toolchain.
install_perl_5100_bin
install_perl_5100_toolchain
$self->install_perl_5100_bin( name => 'perl', dist => 'RGARCIA/perl-5.10.0.tar.gz', unpack_to => 'perl', license => { 'perl-5.10.0/Readme' => 'perl/Readme', 'perl-5.10.0/Artistic' => 'perl/Artistic', 'perl-5.10.0/Copying' => 'perl/Copying', }, install_to => 'perl', );
The install_perl_5100_bin method takes care of the detailed process of building the Perl 5.10.0 binary and installing it into the distribution.
A short summary of the process would be that it downloads or otherwise fetches the named package, unpacks it, copies out any license files from the source code, then tweaks the Win32 makefile to point to the specific build directory, and then runs make/make test/make install. It also registers some environment variables for addition to the Inno Setup script.
It is normally called directly by install_perl_5100 rather than directly from the API, but is documented for completeness.
It takes a number of parameters that are sufficiently detailed above.
Returns true (after 20 minutes or so) or throws an exception on error.
$dist->install_dmake
The install_dmake method installs the dmake make tool into the distribution, and is typically installed during "C toolchain" build phase.
install_dmake
It provides the approproate arguments to install_binary and then validates that the binary was installed correctly.
install_binary
Returns true or throws an exception on error.
$dist->install_gcc
The install_gcc method installs the GNU C Compiler into the distribution, and is typically installed during "C toolchain" build phase.
install_gcc
It provides the appropriate arguments to several install_binary calls. The default install_gcc method installs two binary packages, the core compiler 'gcc-core' and the C++ compiler 'gcc-c++'.
$dist->install_binutils
The install_binutils method installs the GNU binutils package into the distribution.
install_binutils
GNU binutils
The most important of these is dlltool.exe, which is used to extract static library files from .dll files. This is needed by some libraries to let the Perl interfaces build against them correctly.
dlltool.exe
$dist->install_pexports
The install_pexports method installs the MinGW pexports package into the distribution.
install_pexports
MinGW pexports
This is needed by some libraries to let the Perl interfaces build against them correctly.
$dist->install_mingw_runtime
The install_mingw_runtime method installs the MinGW runtime package into the distribution, which is basically the MinGW version of libc and some other very low level libs.
install_mingw_runtime
$dist->install_zlib
The install_zlib method installs the GNU zlib compression library into the distribution, and is typically installed during "C toolchain" build phase.
install_zlib
It provides the appropriate arguments to a install_library call that will extract the standard zlib win32 package, and generate the additional files that Perl needs.
install_library
$dist->install_win32api
The install_win32api method installs MinGW win32api layer, to allow C code to compile against native Win32 APIs.
install_win32api
MinGW win32api
$dist->install_mingw_make
The install_mingw_make method installs the MinGW build of the GNU make build tool.
install_mingw_make
While GNU make is not used by Perl itself, some C libraries can't be built using the normal dmake tool and explicitly need GNU make. So we install it as mingw-make and certain Alien:: modules will use it by that name.
dmake
$dist->install_libiconv
The install_libiconv method installs the GNU libiconv library, which is used for various character encoding tasks, and is needed for other libraries such as libxml.
install_libiconv
GNU libiconv
libxml
$dist->install_libxml
The install_libxml method installs the Gnome libxml library, which is a fast, reliable, XML parsing library, and the new standard library for XML parsing.
install_libxml
Gnome libxml
$dist->install_expat
The install_expat method installs the Expat XML library, which was the first popular C XML parser. Many Perl XML libraries are based on Expat.
install_expat
Expat
$dist->install_gmp
The install_gmp method installs the GNU Multiple Precision Arithmetic Library, which is used for fast and robust bignum support.
install_gmp
GNU Multiple Precision Arithmetic Library
$dist->install_pari
The install_pari method install (via a PAR package) libpari and the Math::Pari module into the distribution.
install_pari
This method should only be called at during the install_modules phase.
$self->install_binary( name => 'gmp', );
The install_gmp method is used by library-specific methods to install pre-compiled and un-modified tar.gz or zip archives into the distribution.
$self->install_distribution( name => 'ADAMK/File-HomeDir-0.69.tar.gz, force => 1, automated_testing => 1, makefilepl_param => [ 'LIBDIR=' . File::Spec->catdir( $self->image_dir, 'c', 'lib', ), ], );
The install_distribution method is used to install a single CPAN or non-CPAN distribution directly, without installing any of the dependencies for that distribution.
install_distribution
It is used primarily during CPAN bootstrapping, to allow the installation of the toolchain modules, with the distribution install order precomputed or hard-coded.
It takes a compulsory 'name' param, which should be the AUTHOR/file path within the CPAN mirror.
The optional 'force' param allows the installation of distributions with spuriously failing test suites.
The optional 'automated_testing' param allows for installation with the AUTOMATED_TESTING environment flag enabled, which is used to either run more-intensive testing, or to convince certain Makefile.PL that insists on prompting that there is no human around and they REALLY need to just go with the default options.
AUTOMATED_TESTING
The optional 'makefilepl_param' param should be a reference to an array of additional params that should be passwd to the perl Makefile.PL. This can help with distributions that insist on taking additional options via Makefile.PL.
perl Makefile.PL
Returns true of throws an exception on error.
$self->install_module( name => 'DBI', );
The install_module method is a high level installation method that can be used during the install_perl_modules phase, once the CPAN toolchain has been been initialized.
install_module
install_perl_modules
It makes the installation call using the CPAN client directly, allowing the CPAN client to both do the installation and fulfill all of the dependencies for the module, identically to if it was installed from the CPAN shell via an "install Module::Name" command.
The compulsory 'name' param should be the class name of the module to be installed.
The optional 'force' param can be used to force the install of module. This does not, however, force the installation of the dependencies of the module.
$self->install_modules( qw{ Foo::Bar This::That One::Two } );
The install_modules method is a convenience shorthand that makes it trivial to install a series of modules via install_module.
install_modules
As a convenience, it does not support any additional params to the underlying install_module call other than the name.
The install_par method extends the available installation options to allow for the install of pre-compiled modules and pre-compiled C libraries via "PAR" packages.
install_par
The compulsory 'name' param should be a simple identifying name, and does not have any functional use.
The compulsory 'uri' param should be a URL string to the PAR package.
Returns true on success or throws an exception on error.
# Overwrite the CPAN::Config $self->install_file( share => 'Perl-Dist CPAN_Config.pm', install_to => 'perl/lib/CPAN/Config.pm', ); # Install a custom icon file $self->install_file( name => 'Strawberry Perl Website Icon', url => 'http://strawberryperl.com/favicon.ico', install_to => 'Strawberry Perl Website.ico', );
The install_file method is used to install a single specific file from various sources into the distribution.
install_file
It is generally used to overwrite modules with distribution-specific customisations, or to install licenses, README files, or other miscellaneous data files which don't need to be compiled or modified.
It takes a variety of different params.
The optional 'name' param provides an optional plain name for the file. It does not have any functional purpose or meaning for this method.
One of several alternative source methods must be provided.
The 'url' method is used to provide a fully-resolved path to the source file and should be a fully-resolved URL.
The 'file' method is used to provide a local path to the source file on the local system, and should be a fully-resolved filesystem path.
The 'share' method is used to provide a path to a file installed as part of a CPAN distribution, and accessed via File::ShareDir.
It should be a string containing two space-seperated value, the first of which is the distribution name, and the second is the path within the share dir of that distribution.
The final compulsory method is the 'install_to' method, which provides either a destination file path, or alternatively a path to an existing directory that the file be installed below, using its source file name.
$self->install_launcher( name => 'CPAN Client', bin => 'cpan', );
The install_launcher method is used to describe a binary program launcher that will be added to the Windows "Start" menu when the distribution is installed.
install_launcher
It takes two compulsory param.
The compulsory 'name' param is the name of the launcher, and the text that label will be displayed in the start menu (Currently this only supports ASCII, and is not language-aware in any way).
The compulsory 'bin' param should be the name of a .bat script launcher in the Perl bin directory. The program itself MUST be installed before trying to add the launcher.
$self->install_website( name => 'Strawberry Perl Website', url => 'http://strawberryperl.com/', icon_file => 'Strawberry Perl Website.ico', icon_index => 1, );
The install_website param is used to install a "Start" menu entry that will load a website using the default system browser.
install_website
The compulsory 'name' param should be the name of the website, and will be the labelled displayed in the "Start" menu.
The compulsory 'url' param is the fully resolved URL for the website.
The optional 'icon_file' param should be the path to a file that contains the icon for the website.
The optional 'icon_index' param should be the icon index within the icon file. This param is optional even if the 'icon_file' param has been provided, by default the first icon in the file will be used.
Returns true on success, or throws an exception on error.
$self->write_exe;
The write_exe method is used to generate the compiled installer executable. It creates the entire installation file tree, and then executes InnoSetup to create the final executable.
write_exe
This method 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.
The write_zip method is used to generate a standalone .zip file containing the entire distribution, for situations in which a full installer executable is not wanted (such as for "Portable Perl" type installations).
write_zip
Bugs should be reported via the CPAN bug tracker
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Perl-Dist
For other issues, or commercial enhancement or support, contact the author.
Adam Kennedy <adamk@cpan.org>
Perl::Dist, vanillaperl.com, http://ali.as/
Copyright 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, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Perl::Dist
CPAN shell
perl -MCPAN -e shell install Perl::Dist
For more information on module installation, please visit the detailed CPAN module installation guide.