GRINDPERL(1)

📦
version 0.004 · 2 versions
, in fedora 43

💖 GRINDPERL(1) 💖

okay bestie, listen up — this is the grindperl page from the User Contributed Perl Documentation section of the manual, and it's literally about building bleadperl without losing your entire mind. Pull up a chair, we're doing this together. 🫶

✨ NAME ✨

grindperl — a command-line tool that helps you build and test bleadperl. no cap. that's the whole job. 💅

🌸 VERSION 🌸

version 0.004 — yeah she's a lil baby version number but she's doing great. 🎀

🦋 SYNOPSIS 🦋

bestie these commands are intended to be run from inside a clone of the Perl git repository. don't just run them in your home directory, i'm begging. 😭

  # 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 🌈

so here's the tea 🍓: hacking on the Perl source tree means you have to build and test constantly. like, over and over. it's giving cardio. the grindperl tool automates some of those common configuration, build and test tasks for you. most Perl 5 porters have written something like this themselves, and the author is putting theirs on CPAN to help new contributors (or the less-automated ones among us) get their lives together. 🫶

instead of typing all of 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 and go touch grass:

  $ grindperl

and if you want to run make test_porting before committing, or before merging a submitted patch — which is strongly encouraged, bestie, do not skip this — it's literally as easy as:

  $ grindperl --porting

generally, unless options say otherwise, these steps happen in order:

  • 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

and if anything fails along the way, grindperl stops dead with an error message. she will not push through the pain. 💀

👑 OPTIONS 👑

any boolean option that defaults to true can be negated by sticking no- in front of its long form, e.g. --no-threads. periodt.

💅 --config

boolean flag. when you set it, grindperl halts right after running Configure. default is false.

💅 --jobs=N or -j N

controls how many parallel make jobs run. defaults to 9.

💅 --testjobs=N or -t N

controls how many parallel test jobs run. defaults to 9. set this to 0 and it will run make test_prep but won't run any tests.

💅 --porting

boolean flag. when set, make test_porting runs instead of make test_harness. the number of jobs run in parallel still comes from the --testjobs option. default is false.

💅 --install

boolean flag. when set, grindperl runs make install after every other step. be sure to set --prefix to a writeable destination or you're gonna have a bad time. default is false.

💅 --output FILE or -o FILE

tells grindperl to merge STDERR and STDOUT together and redirect the output into the given file, so you can capture all your build/test results. 📝

💅 --prefix PATH

sets an explicit installation path via -Dprefix=....

if you don't set it, a default prefix gets calculated relative to --install_root.

if a .git directory exists, the prefix will look like ROOT/BRANCH-DESCRIBE if a branch can be figured out, or ROOT/fromgit-DESCRIBE if the branch can't be determined (like from a detached HEAD). e.g. with the default --install_root of /tmp, the prefix for the blead branch might look like:

  /tmp/blead-v5.15.1-22-g5213914

this makes sure the prefix is different for different spots in the commit history. iconic behaviour honestly. ✨

if there's no .git directory, then the prefix will look like 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 make sure different grindperl runs generally don't 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 you actually have write permissions for, bestie.

💅 --debugging

boolean flag. sets -DDEBUGGING. default is true.

💅 --threads

boolean flag. sets -Dusethreads. default is true.

💅 --cache

boolean flag. when true, grindperl saves your config.sh and Policy.sh files into a hidden cache file. if those files exist, it restores them and runs Configure with the -r option.

⚠️ using cached config files from a different commit can break things and is not recommended. i said what i said.

defaults to false.

💅 --man

boolean flag. when false, grindperl disables man directories and man files will not be generated or installed. defaults to false.

💅 --verbose or -v

outputs some extra progress messages and warnings. for the girlies who need to know everything. 🙈

💅 --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. don't forget the space, i'm serious. 😤

💅 --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. proceed with caution, bestie. 🧚

🎀 CONFIGURATION FILE 🎀

you can put command-line options into a configuration file, one per line, and they get prepended to @ARGV before options are processed. here's what the author has in their 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, make 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>

this software is Copyright (c) 2011 by David Golden.

this is free software, licensed under:

  The Apache License, Version 2.0, January 2004

and that's the whole page, bestie!! 🦋 this was perl v5.42.0, dated 2025-07-25, and it's the GRINDPERL(1) page. go build some perl, you absolute icon. 👑✨💖

📦 where this page comes from