=pod

=encoding utf8

=for HTML <a href="https://www.github.com/briandfoy/PerlPowerTools/actions?query=workflow%3Amacos"><img src="https://www.github.com/briandfoy/PerlPowerTools/workflows/macos/badge.svg"></a>

=for HTML <a href="https://www.github.com/briandfoy/PerlPowerTools/actions?query=workflow%3Aubuntu"><img src="https://www.github.com/briandfoy/PerlPowerTools/workflows/ubuntu/badge.svg"></a>

=for HTML <a href="https://www.github.com/briandfoy/PerlPowerTools/actions?query=workflow%3Awindows"><img src="https://www.github.com/briandfoy/PerlPowerTools/workflows/windows/badge.svg"></a>

=for HTML <a href='https://ci.appveyor.com/project/briandfoy/PerlPowerTools'><img src='https://ci.appveyor.com/api/projects/status/9visklo7hlsvsv6n?svg=true' /></a>

=for HTML <a href='https://coveralls.io/github/briandfoy/PerlPowerTools?branch=master'><img src='https://coveralls.io/repos/github/briandfoy/PerlPowerTools/badge.svg?branch=master' alt='Coverage Status' /></a>

=for HTML <a href="https://github.com/briandfoy/PerlPowerTools/blob/master/LICENSE"><img src="https://img.shields.io/cpan/l/PerlPowerTools.svg" /></a>

=for HTML <a href="https://metacpan.org/pod/PerlPowerTools"><img src="https://img.shields.io/cpan/v/PerlPowerTools.svg" /></A>


=head1 The PerlPowerTools module

This is the I<README> for the L<PerlPowerTools> Perl module. This
distribution provides pure-Perl implementations of popular Unix tools
aimed at the less fortunate systems that don't come with them. By default,
these install into F<~/perlpowertools>.

There are some other ways that might get you to the same thing (and
are probably better supported):

=over 4

=item * With the L<Windows Subsytem for Linux|https://docs.microsoft.com/en-us/windows/wsl/> (WSL), you can run a linux right in a console

=item * The L<GNU coreutils|https://www.gnu.org/software/coreutils>

=item * L<Cygwin|https://www.cygwin.com>

=item * L<GNUWin|http://gnuwin32.sourceforge.net/summary.html>

=back

=head2 Documentation

To read about L<PerlPowerTools>, look at the embedded documentation
in the module itself. Inside the distribution, you can format it
with L<perldoc|https://perldoc.perl.org/perldoc.html>:

	% perldoc lib/PerlPowerTools.pm

If you have already installed the module, you can specify the module
name instead of the file location:

	% perldoc PerlPowerTools

You can read the documentation and inspect the meta data at
L<MetaCPAN|https://metacpan.org/pod/PerlPowerTools>.

The standard module documentation has example uses in the SYNOPSIS
section, but you can also look in the I<examples/> directory (if it's
there), or look at the test files in I<t/>.

=head2 Installation

You can install this module with a CPAN client, which will resolve
and install the dependencies:

	% cpan PerlPowerTools
	% cpanm PerlPowerTools

You can also install directly from the distribution directory, which
will also install the dependencies:

	% cpan .
	% cpanm .

You could install just this module manually:

	% perl Makefile.PL
	% make
	% make test
	% make install

If you didn't specify INSTALL_BASE, the modules go into your home
directory under F<perlpowertools>. You'll need to add this to PATH
to be able to use them.

If you want to install them somewhere else, run the Makefile.PL
with your installation location:

    perl Makefile.PL INSTALL_BASE=/where/you/want/them/to/go

=head2 Source location

The meta data, such as the source repository and bug tracker, is in
I<Makefile.PL> or the I<META.*> files it creates. You can find that on
those CPAN web interfaces, but you can also look at files directly in
the source repository: L<https://github.com/briandfoy/PerlPowerTools>

If you find a problem, file a ticket in the L<issue
tracker|https://github.com/briandfoy/PerlPowerTools/issues>.

There are also backup repositories hosted on other services. These
reflect the state of the main repo and exist only for redundancy:

=over 4

=item * L<https://bitbucket.com/briandfoy/PerlPowerTools>

=item * L<https://codeberg.org/briandfoy/PerlPowerTools>

=item * L<https://gitlab.com/briandfoy/PerlPowerTools>

=back

=head2 GitHub Attestation

Starting with v1.046, PerlPowerTools now uses
L<GitHub Attestations|https://github.blog/2024-05-02-introducing-artifact-attestations-now-in-public-beta/>,
which allow you to verify that the archive file you have was made from
the official repo.

You need a GitHub account and the L<gh tool|https://github.com/larsks/ghcli>.

	# download the distro file from GitHub, MetaCPAN, or a CPAN mirror
	$ gh auth login
	...follow instructions...
	$ gh attestation verify PerlPowerTools-1.046.tar.gz --owner briandfoy

=head2 Getting help

Although I'm happy to hear from module users in private email,
that's the best way for me to forget to do something.

Besides the issue trackers, you can find help at
L<Perlmonks|http://www.perlmonks.org> or
L<Stackoverflow|http://www.stackoverflow.com>, both of which have many
competent Perlers who can answer your question, almost in real time.
They might not know the particulars of this module, but they can help
you diagnose your problem.

You might like to read L<brian's Guide to Solving Any Perl
Problem|https://briandfoy.github.io/brians-guide-to-solving-any-perl-problem/>.

=head2 Copyright and License

You should have received a I<LICENSE> file, but the license is also noted
in the module files. About the only thing you can't do is pretend that
you wrote code that you didn't.

=head2 Good luck!

Enjoy,

brian d foy, briandfoy@pobox.com

=cut
