#!perl
use v5.10.0;
use strict;
use warnings;
our $VERSION = '0.001'; # VERSION

use App::grindperl;
my $app = App::grindperl->new;
exit $app->run;

# PODNAME: grindperl
# ABSTRACT: Command-line tool to help build and test bleadperl



=pod

=head1 NAME

grindperl - Command-line tool to help build and test bleadperl

=head1 VERSION

version 0.001

=head1 SYNOPSIS

These commands are intended to be run from within a clone of
the Perl git repository.

   # Configure && make && make test (in parallel)
   $ grindperl
 
   # Configure && make && make test_porting (in parallel)
   $ grindperl --porting
 
   # Same as first example, but without threads
   $ grindperl --no-threads
 
   # Configure/make/test and install
   $ grindperl --prefix=/opt/perl/blead --install

=head1 DESCRIPTION

Hacking on the Perl source tree requires one to regularly build and test.  The
C<<< grindperl >>> tool helps automate some common configuration, build and test
tasks.  Most Perl 5 porters have written something like this and I'm putting
mine on CPAN to help new (or less automated) contributors.

Instead of typing this:

   $ ./Configure -des -Duse_devel -Dcc='ccache=gcc' \
     -Dprefix=/tmp/blead-$(git describe) -DDEBUGGING \
     -Dusethreads
   $ make -j 9 test_prep
   $ TEST_JOBS=9 make test_harness

You can just type this:

   $ grindperl

If you want to run C<<< make test_porting >>> before committing or before
merging a submitted patch -- which is strongly encouraged -- that is
as easy as:

   $ grindperl --porting

Generally, the following steps are taken (unless modified by options):

=over

=item *

clean the source directory, with C<<< git clean -dxf >>> or C<<< make distclean >>>
as necessary

=item *

run C<<< Configure >>> with desired options

=item *

run either C<<< make test_harness >>> or C<<< make test_porting >>> or C<<< make test_prep >>>
depending on various options

=back

If anything fails along the way, C<<< grindperl >>> will stop with an error message.

=head1 OPTIONS

Any boolean options that default to true may be negated by prefixing their long
form with C<<< no- >>>, e.g. C<<< --no-threads >>>.

=head2 --config

Boolean flag.  When set, C<<< grindperl >>> will halt after running C<<< Configure >>>.
Default is false.

=head2 --jobs=N or -j N

Controls how many parallel make jobs to run.  Defaults to 9.

=head2 --testjobs=N or -t N

Controls the number of parallel test jobs to run.  Defaults to 9.
Setting this to 0 will run C<<< make test_prep >>> but will not run tests.

=head2 --porting

Boolean flag.  When set, C<<< make test_porting >>> will be run instead
of C<<< make test_harness >>>.  The number of jobs to run in parallel
will still be based on the C<<< --testjobs >>> option.  Default is false.

=head2 --install

Boolean flag.  When set, C<<< grindperl >>> will run C<<< make install >>> after all
other steps.  Be sure to set C<<< --prefix >>> to a writeable destination.  Default
is false.

=head2 --output FILE or -o FILE

Instructs C<<< grindperl >>> to merge STDERR and STDOUT and redirect output
to the given file to capture buildE<sol>test results.

=head2 --prefix PATH

Sets an explicit installation path via C<<< -Dprefix=... >>>.

If not set, a default prefix will be calculated relative to C<<< --install_root >>>.

If a C<<< .git >>> directory exists, the prefix will resemble C<<< ROOT/BRANCH-DESCRIBE >>>
if a branch can be determined or C<<< ROOT/fromgit-DESCRIBE >>> if the branch cannot
be determined (as from a detached HEAD).  E.g. given the default C<<< --install_root >>>
of C<<< /tmp >>>, the prefix for the blead branch might resemble this:

   /tmp/blead-v5.15.1-22-g5213914

This ensures the the prefix is different for different places in the
commit history.

If there is no C<<< .git >>> directory, then the prefix will resemble
C<<< ROOT/DIRNAME-EPOCH >>> where DIRNAME is the name of the current directory
and EPOCH is the number of epoch seconds.

   /tmp/perl-5.15.1-1311278560

These prefix choices ensure that installing different grindperl runs
will generally not clobber each other.

=head2 --install_root

A base path for a generated default C<<< --prefix >>>. The default install root
is C<<< /tmp >>>.  This needs to be a directory for which you have write
permissions.

=head2 --debugging

Boolean flag.  Sets C<<< -DDEBUGGING >>>.  Default is true.

=head2 --threads

Boolean flag.  Sets C<<< -Dusethreads >>>.  Default is true.

=head2 --cache

Boolean flag.  When true, C<<< grindperl >>> will save your C<<< config.sh >>>
and C<<< Policy.sh >>> files to a hidden cache file.  If these files
exist, it will restore them and run C<<< Configure >>> with the C<<< -r >>> option.

Using cached config files from a different commit can break things
and is not recommended.

Defaults to false.

=head2 --man

Boolean flag.  When false, C<<< grindperl >>> will disable man diretories
and man files will not be generated or installed.  Defaults to false.

=head2 --verbose or -v

Outputs some extra progress messages and warninsg.

=head2 --define KEY=VALUE or -D KEY=VALUE

=head2 --undefine KEY or -U KEY

May be specified multiple times with different values of KEY.  These
set the C<<< -D >>> and C<<< -U >>> options for C<<< Configure >>>.  Not that unlike C<<< Configure >>>,
these require a space between the opton and the key or keyE<sol>value pair.

=head1 CONFIGURATION FILE

You can put command line options into a configuration file, one per line,
and they will be prepended to C<<< @ARGV >>> before options are processed.  For
example, here is what I have in my config file.

     --install_root=/opt/perl
     -D cc='ccache gcc'
     -D cf_by=dagolden
     -D cf_email='dagolden@cpan.org'
     -D perladmin='dagolden@cpan.org'

To edit the config file, be sure your C<<< EDITOR >>> environment variable is set
and then run C<<< grindperl --edit >>>.

=head1 CAVEATS

=over

=item *

You must have git installed and in your path

=item *

This depends on certain shell redirection constructs and is unlikely to
work on non-POSIX systems

=back

=head1 AUTHOR

David Golden <dagolden@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is Copyright (c) 2011 by David Golden.

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004

=cut


__END__


# vim: ts=2 sts=2 sw=2 et:
