grindperl man page

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

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

Author

David Golden <dagolden@cpan.org>

Info

2015-12-09 perl v5.24.1 User Contributed Perl Documentation