NAME
Setup - Specification for setup module
VERSION
version 1.0.4
SPECIFICATION VERSION
1.0
SPECIFICATION
This is a specification for setup modules. Setup modules are normal Perl modules that live under the Setup::
namespace and contain setup functions. Setup functions are normal Perl subroutines, typically named with setup_
prefix (like setup_file
, setup_unix_user
, etc.) They are typically used for, well, setting up stuffs, like software installation, system setup, or configuration management.
Setup functions MUST have metadata, as specified in Rinci specification.
Setup function MUST use Log::Any for logging.
Setup functions MUST support transactions, as described in Rinci::Transaction.
Since setup functions might be used in unsetup (uninstallation) of software months or even years after setup (installation), their interface should be stable. During setup, undo actions are recorded in transaction database and might be used years later.
Setup function should log something like this in the check_state
phase when in dry-run mode, to give messages to user:
my $tx_action = $args{-tx_action};
my $dry_run = $args{-dry_run};
if ($tx_action eq 'check_state') {
...
$log->infof("(DRY) Trashing %s ...", $path);
return [200, "Path $path should be trashed", undef, {undo_actions=>\@u}];
}
Setup function should log something like this when about to perform action in fix_state
phase:
# example 1: trashing a file
$log->infof("Trashing %s ...", $path);
$trash->trash($path);
# example 2: creating a user
$log->infof("Adding user %s ...", $user);
$res = add_user(user=>$user, ...);
AUTHOR
Steven Haryanto <stevenharyanto@gmail.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2012 by Steven Haryanto.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
CHANGES
Version 1.0.4 (2012-09-04)
Specify how function should log dry-run message and message before
performing action in 'fix_state' phase.
Version 1.0.3 (2012-08-21)
Follow Rinci 1.1.24. Simplify description (idempotency is implied by
transaction protocol). Remove requirement of using
Perinci::Sub::Gen::Undoable since it is now deprecated.
Version 1.0.2 (2012-08-14)
No functional changes. Follow Rinci 1.1.23. Simplify description.
Version 1.0.1 (2012-05-31)
Simplify description, as most functionality is now already described in
more detail by Rinci 1.1.17+ and Riap 1.1.13+'s transaction/undo
protocol.
Version 1.0.0 (2012-03-28)
First release, split from Setup-File.