grindperl - Man Page

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

2024-07-18 perl v5.40.0 User Contributed Perl Documentation