grindperl man page

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


version 0.004


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


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 \
$ 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.


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


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.


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.


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:


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.


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


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.


Boolean flag. Sets "-DDEBUGGING". Default is true.


Boolean flag. Sets "-Dusethreads". Default is true.


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.


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.

-D cc='ccache gcc'
-D cf_by=dagolden
-D cf_email='dagolden@cpan.org'
-D perladmin='dagolden@cpan.org'
-D optimize=-g

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


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


David Golden <dagolden@cpan.org>