package Setup; # to make podweaver happy

# VERSION

1;
# ABSTRACT: Specification for setup module

__END__

=pod

=encoding UTF-8

=head1 NAME

Setup - Specification for setup module

=head1 SPECIFICATION VERSION

1.0

=head1 VERSION

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

=head1 SPECIFICATION

This is a specification for setup modules. Setup modules are normal Perl modules
that live under the C<Setup::> namespace and contain setup functions. Setup
functions are normal Perl subroutines, typically named with C<setup_> prefix
(like C<setup_file>, C<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 L<Rinci> specification.

Setup function MUST use L<Log::ger> for logging.

Setup functions MUST support transactions, as described in
L<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 C<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
C<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, ...);

=head1 HOMEPAGE

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

=head1 SOURCE

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

=head1 BUGS

Please report any bugs or feature requests on the bugtracker website L<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.

=head1 AUTHOR

perlancar <perlancar@cpan.org>

=head1 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.

=cut
