The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Perl-Dist-WiX-1.100
River stage one • 1 direct dependent • 1 total dependent
/ Perl::Dist::WiX::Checkpoint

NAME

Perl::Dist::WiX::Checkpoint - Checkpoint support for Perl::Dist::WiX

VERSION

This document describes Perl::Dist::WiX::Checkpoint version 1.100.

DESCRIPTION

This module provides the routines that Perl::Dist::WiX uses in order to support checkpointing.

SYNOPSIS

        # This module is not to be used independently.
        $dist = Perl::Dist::WiX->new(
                # ...
                checkpoint_before => 5
                checkpoint_after => [8, 9],
                checkpoint_stop => 9,
                # ...
        );

INTERFACE

There are 2 portions to the interface to this module - the parameters to new() (listed under Parameters below), and the object calls that Perl::Dist::WiX uses to coordinate checkpointing.

Parameters

tasklist

        $dist = Perl::Dist::WiX->new(
                # ...
                tasklist => [
                        # Install the core C toolchain
                        'install_c_toolchain',

                        # Install any additional C libraries
                        'install_c_libraries',

                        # Install the Perl binary
                        'install_perl',

                        # Install the Perl toolchain
                        'install_perl_toolchain',

                        # Install additional Perl modules
                        'install_cpan_upgrades',

                        # Install the Win32 extras
                        'install_win32_extras',

                        # Apply optional portability support
                        'install_portable',

                        # Remove waste and temporary files
                        'remove_waste',

                        # Regenerate file fragments
                        'regenerate_fragments',
                        
                        # Install any extra custom non-Perl software on top of Perl.
                        # This is primarily added for the benefit of Parrot.
                        'install_custom',

                        # Write out the distributions
                        'write',
                ];
                # ...
        );

This is the parameter that specifies what tasks to execute. The names are of 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.

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

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

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_task

checkpoint_task executes a portion of creating an installer.

The first parameter is the name of the subroutine to be executed.

The second parameter is the task number that goes with that subroutine.

Returns true (technically, the object that called it), or throws an exception.

checkpoint_file

Returns the file that the Perl::Dist::WiX object is stored in.

checkpoint_self

Currently unimplemented, and throws an exception saying so.

checkpoint_save

Saves a checkpoint within the checkpoint subdirectory of Perl::Dist::WiX->temp_dir

checkpoint_save

Restores a checkpoint saved to the checkpoint subdirectory of Perl::Dist::WiX->temp_dir with "checkpoint_save".

DIAGNOSTICS

See Perl::Dist::WiX::Diagnostics for a list of exceptions that this module can throw.

BUGS AND LIMITATIONS (SUPPORT)

WARNING: The checkpointing facility in this module is NOT stable. It is currently implemented using Storable with the $Storable::Deparse variable set to 1 (localized, of course). This probably WILL change in the future, as when checkpoints are reloaded, hash entries are appearing that weren't intended to be there. I am also not sure that references that were weakened are weakened when reloaded.

Restored checkpoints currently crash with "Free in wrong pool" errors in global destruction - if an exception occurs, they're reported there instead.

Do NOT use this in production. Debugging a distribution using the facilities provided here is fine.

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::WiX, http://ali.as/, http://csjewell.comyr.com/perl/

COPYRIGHT AND LICENSE

Copyright 2009 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 distribution.