Perl::Dist::WiX::Util::Machine - Generate an entire set of related distributions

This document describes Perl::Dist::WiX::Util::Machine version 1.500002.

	# This is what Perl::Dist::Strawberry will do, as of version 2.03.

	# Create the machine
	my $machine = Perl::Dist::WiX::Util::Machine->new(
		class  => 'Perl::Dist::Strawberry',
		common => [ forceperl => 1 ],
		skip   => [4, 6],
	);

	# Set the different versions
	$machine->add_dimension('version');
	$machine->add_option('version',
		perl_version => '5101',
	);
	$machine->add_option('version',
		perl_version => '5101',
		portable     => 1,
	);
	$machine->add_option('version',
		perl_version => '5121',
		relocatable  => 1,
	);

	# Set the different paths
	$machine->add_dimension('drive');
	$machine->add_option('drive',
		image_dir => 'C:\strawberry',
	);
	$machine->add_option('drive',
		image_dir => 'D:\strawberry',
		msi       => 1,
		zip       => 0,
	);

	$machine->run();
	# Creates 8 distributions (really 6, because you can't have
	# portable => 1 and zip => 0 for the same distribution,
	# nor do we need to build a relocatable version twice.)	

Perl::Dist::WiX::Util::Machine is a Perl::Dist::WiX multiplexer.

It provides the functionality required to generate several variations of a distribution at the same time.

	my $machine = Perl::Dist::WiX::Util::Machine->new(
		class => 'Perl::Dist::WiX',
		common => { forceperl => 1, },
		output => 'C:\',
		trace  => 2,
	);

This method creates a new object that generates multiple distributions, using the parameters below.

This required parameter specifies the class that this object uses to create distributions.

It must be a subclass of Perl::Dist::WiX.

This required parameter specifies the parameters that are common to all the distributions that will be created, as an array or hash reference.

For the parameters that you can put here, see the documentation for the class that is specified in the 'class' parameter and its subclasses.

This is the directory where all the output files will be copied to.

If none is specified, it defaults to what File::HomeDir thinks is the desktop.

This is a reference to a list of distributions to skip building, in numerical order.

Note that the numerical order the distributions is dependent on which order you put the dimensions in - the last dimension is changed first. For example, if there are 3 dimensions, with the first dimension having 3 options and the other 2 dimensions having 2 options, the numbering is as follows:

   1: 1, 1, 1   2: 1, 1, 2   3: 1, 2, 1   4: 1, 2, 2
   5: 2, 1, 1 ...   
   9: 3, 1, 1 ...

If you wanted to skip the two distributions where the first dimension was going to use its second option and the last dimension was going to use its first option, you would pass [ 5, 7 ] to this option.

This is the trace level for all objects.

If none is specified, it defaults to 1.

	$machine->add_dimension('perl_version');

Adds a 'dimension' (a set of options for different distributions) to the machine.

The options are added by add_option calls using this dimension name.

Note that dimensions are multiplicative, so that if there are 3 dimensions defined in the machine, and they each have 3 options, 27 distributions will be generated.

  $machine->add_option('perl_version',
    perl_version => '5120',
    relocatable => 1,
  );

Adds a 'option' (a set of parameters that can change) to a dimension.

The first parameter is the dimension to add the option to, and the other parameters are stored in the dimension to be used when creating objects.

The combination of the 'common' parameters and one option from each dimension is used when creating or iterating through distribution objects.

	my @dists = $machine->all();

Returns an array of objects that create all the possible distributions configured for this machine.

	my $dist = $machine->next();

Returns an object that creates the next possible distribution that is configured for this machine.

	$machine->run();

Tries to create and execute each object that can be created by this machine.

Bugs should be reported via the CPAN bug tracker at

http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Perl-Dist-WiX

For other issues, contact the author.

Curtis Jewell <adamk@cpan.org>

Adam Kennedy <adamk@cpan.org>

Copyright 2009 - 2010 Curtis Jewell.

Copyright 2007 - 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.