The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

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

VERSION

version 0.004

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 -Dusedevel -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):

  • clean the source directory, with git clean -dxf or make distclean

    as necessary

  • run Configure with desired options

  • run either make test_harness or make test_porting or make test_prep

    depending on various 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 directories and man files will not be generated or installed. Defaults to false.

--verbose or -v

Outputs some extra progress messages and warnings.

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

--undefine KEY or -U KEY

--additions KEY=VALUE or -A KEY=VALUE

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

--32 (EXPERIMENTAL)

This experimental flag tries to force as much 32-bitness as possible, even on a 64 bit operating system. It's very hacky, messes with compiler and linker flags and is not guaranteed on all platforms.

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'
    -D optimize=-g
    -A ccflags=-DPERL_USE_SAFE_PUTENV

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

CAVEATS

  • You must have git installed and in your path

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

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