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.
grindperl
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:
make test_porting
$ grindperl --porting
Generally, the following steps are taken (unless modified by options):
clean the source directory, with git clean -dxf or make distclean
git clean -dxf
make distclean
as necessary
run Configure with desired options
Configure
run either make test_harness or make test_porting or make test_prep
make test_harness
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.
no-
--no-threads
Boolean flag. When set, grindperl will halt after running Configure. Default is false.
Controls how many parallel make jobs to run. Defaults to 9.
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.
--testjobs
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.
make install
--prefix
Instructs grindperl to merge STDERR and STDOUT and redirect output to the given file to capture build/test results.
Sets an explicit installation path via -Dprefix=....
-Dprefix=...
If not set, a default prefix will be calculated relative to --install_root.
--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:
.git
ROOT/BRANCH-DESCRIBE
ROOT/fromgit-DESCRIBE
/tmp
/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.
ROOT/DIRNAME-EPOCH
/tmp/perl-5.15.1-1311278560
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.
-DDEBUGGING
Boolean flag. Sets -Dusethreads. Default is true.
-Dusethreads
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.
config.sh
Policy.sh
-r
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.
Outputs some extra progress messages and warnings.
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.
-D
-U
-A
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.
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.
@ARGV
--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.
EDITOR
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>
This software is Copyright (c) 2011 by David Golden.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
To install App::grindperl, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::grindperl
CPAN shell
perl -MCPAN -e shell install App::grindperl
For more information on module installation, please visit the detailed CPAN module installation guide.