/ 
Setup-1.0.6
River stage one • 1 direct dependent • 1 total dependent
/ Setup

NAME

Setup - Specification for setup module

SPECIFICATION VERSION

1.0

VERSION

This document describes version 1.0.6 of Setup (from Perl distribution Setup), released on 2021-08-02.

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.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Setup functions MUST have metadata, as specified in Rinci specification.

Setup function MUST use Log::ger 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, ...);

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Setup.

SOURCE

Source repository is at https://github.com/perlancar/perl-Setup.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Setup

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021, 2015, 2012 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.