NAME

RPi::Const::BuildCheck - canonical wiringPi/I2C Makefile.PL build guards for the RPi:: distribution family

SYNOPSIS

In an XS distribution's Makefile.PL, before WriteMakefile:

use ExtUtils::MakeMaker;

eval {
    require RPi::Const::BuildCheck;
    RPi::Const::BuildCheck->import;
};
if (! $@) {
    RPi::Const::BuildCheck::wiringpi_build_check();   # dists linking wiringPi
    # or, for a raw-I2C dist:
    # RPi::Const::BuildCheck::i2c_build_check();
}

WriteMakefile( ... );

DESCRIPTION

Every XS distribution in the RPi::WiringPi family needs the same Makefile.PL guard: verify its build dependency (the wiringPi library, or the Linux I2C development headers) is present, honour the RPI_DIST_RELEASE bypass so release tarballs can be cut on a non-Pi machine, and - crucially - exit 0 before WriteMakefile when the dependency is missing, so CPAN testers report NA rather than FAIL.

Hand-copying that logic into ~20 distributions caused drift (differing minimum versions) and left latent bugs. This module is the single canonical implementation, pulled in via CONFIGURE_REQUIRES so it is available before configure runs.

The minimum wiringPi version is not stored here - it is "WIRINGPI_MIN_VERSION" in RPi::Const, the family-wide constant. This module reads it into $RPi::Const::BuildCheck::MIN_WIRINGPI_VERSION; bumping the family minimum is a single edit to that constant and one RPi::Const release.

PACKAGE VARIABLES

$MIN_WIRINGPI_VERSION

The minimum acceptable wiringPi version, read from "WIRINGPI_MIN_VERSION" in RPi::Const at load time (falling back to a literal only if RPi::Const can't be loaded).

FUNCTIONS

wiringpi_build_check(%opts)

For distributions that link -lwiringPi. Returns true when the requirement is satisfied (or bypassed via RPI_DIST_RELEASE); otherwise it invokes the "not available" action (by default: print a message and exit 0).

It checks, in order: the RPI_DIST_RELEASE bypass; that wiringPi.h exists in an include directory; that gpio -v reports a version; that the version parses; and that it is greater than or equal to "$MIN_WIRINGPI_VERSION" using an integer (major, minor) tuple comparison. An unparseable or absent version is treated as NA, never a silent pass.

Header discovery searches /usr/include and /usr/local/include, and on a miss also consults the C compiler's own <...> search path (parsed from its verbose preprocessor output), so a wiringPi installed outside the two default prefixes is still found. Passing include_dirs overrides this with an exact list and skips the compiler probe.

All I/O is injectable so the logic is testable off-Pi:

include_dirs => \@dirs      # exact header search path (skips cc probe)
cc           => $path       # C compiler to probe (default $ENV{CC} || cc)
cc_output    => $string     # canned `cc -E -Wp,-v` output
gpio_output  => $string     # canned `gpio -v` output
gpio_path    => $path       # path to the gpio binary
min_version  => $string     # override the minimum
env_release  => $bool       # override $ENV{RPI_DIST_RELEASE}
na           => $coderef     # action on an unsatisfied check ($msg -> ...)

i2c_build_check(%opts)

For distributions that use the raw Linux I2C userspace interface (linux/i2c-dev.h) rather than wiringPi. Same NA-not-FAIL and RPI_DIST_RELEASE semantics; checks that the I2C development headers are present, using the same broadened discovery as "wiringpi_build_check(%opts)" (default prefixes, then the compiler's search path). Accepts include_dirs, headers, cc, cc_output, env_release and na opts.

version_ge($have, $want)

Returns true if wiringPi version $have is greater than or equal to $want, comparing major then minor as integers (so 3.8 is older than 3.18). Returns false if either version is missing or not \d+.\d+.

SEE ALSO

RPi::Const, whose WIRINGPI_MIN_VERSION constant is the canonical minimum.

AUTHOR

Steve Bertrand, <steveb at cpan.org>

LICENSE AND COPYRIGHT

Copyright 2026 Steve Bertrand.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License (2.0).