David Golden > App-grindperl-0.001 > grindperl

Download:
App-grindperl-0.001.tar.gz

Annotate this POD

Website

View/Report Bugs
Source   Latest Release: App-grindperl-0.002

NAME ^

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

VERSION ^

version 0.001

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

DESCRIPTION ^

Hacking on the Perl source tree requires one to regularly build and test. The 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 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):

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

OPTIONS ^

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

--config

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

--jobs=N or -j N

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

--testjobs=N or -t N

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

--porting

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

--install

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

--output FILE or -o FILE

Instructs grindperl to merge STDERR and STDOUT and redirect output to the given file to capture build/test results.

--prefix PATH

Sets an explicit installation path via -Dprefix=....

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

If a .git directory exists, the prefix will resemble ROOT/BRANCH-DESCRIBE if a branch can be determined or ROOT/fromgit-DESCRIBE if the branch cannot be determined (as from a detached HEAD). E.g. given the default --install_root of /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 .git directory, then the prefix will resemble 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.

--install_root

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

--debugging

Boolean flag. Sets -DDEBUGGING. Default is true.

--threads

Boolean flag. Sets -Dusethreads. Default is true.

--cache

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

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

Defaults to false.

--man

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

--verbose or -v

Outputs some extra progress messages and warninsg.

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

--undefine KEY or -U KEY

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

CONFIGURATION FILE ^

You can put command line options into a configuration file, one per line, and they will be prepended to @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 EDITOR environment variable is set and then run grindperl --edit.

CAVEATS ^

AUTHOR ^

David Golden <dagolden@cpan.org>

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
syntax highlighting: