Devel::...tending(3)

💅 Devel::...tending(3) — like, the whole "how do I write my own Devel::AssertOS module" situation

okay bestie so this is a User Contributed Perl Documentation page, and it's about Devel::...tending — actually it's Devel::AssertOS::Extending, the manual that teaches you how to write your own Devel::AssertOS::* modules. yes it's meta. yes it ate. let's go 🫶

✨ NAME ✨

Devel::AssertOS::Extending — the guide for writing Devel::AssertOS::* modules that check what platform they're running on. literally what it says on the tin 🎀

🌸 DESCRIPTION 🌸

Devel::AssertOS::* modules get used by Devel::CheckOS to figure out what OS it's living on. there's a whole set of them shipped for you, and they should correctly detect all platforms that perl currently runs on — plus they detect OS "families" like 'Unix' and 'Windows'. iconic multitasking ✨

you can also use Devel::AssertOS::* modules completely on their own to quickly check whether you're running on the right platform. no entourage needed 💅

if you try to use a Devel::AssertOS module on the wrong platform, it will die by calling Devel::CheckOS::die_unsupported(). and that's not a bad thing, bestie — that conveniently spits out exactly the text CPAN-testers look for to see if your code failed simply because they're doing something as silly as testing your Solaris-only code on HPUX. 😭🙈 it's giving "graceful exit" and honestly we love that for us.

---

🦋 HOW TO WRITE YOUR OWN MODULES 🦋

so you wanna add support for new platforms? slay. you need to write a module called Devel::AssertOS::PlatformName and it should look like this, exactly:

package Devel::AssertOS::Linux;
use Devel::CheckOS;
use strict;
use warnings;
no warnings 'redefine';
our $VERSION = '1.0';
sub os_is { $^O =~ /^linux$/i ? 1 : 0; }
Devel::CheckOS::die_unsupported() unless(os_is());
1;

and that's it. that's the whole vibe. periodt. 🔥

the subroutine must be called os_is and loading the module must die in precisely that manner if your code is running on the wrong platform. that's the contract and we respect it.

it's a good idea to check $^O case-insensitively as it's not consistent. (rude of it, honestly, but whatever.)

🚨 note that it is an error to say:

sub os_is { 1; }

and assume "well, on the wrong platform that'll never get reached because the module can't load". NOPE. because the module can load, and indeed does get loaded — some functions in Devel::CheckOS do things like:

eval "use Devel::AssertOS::$os";

to suppress the error. sneaky? kinda. correct? yeah. 💀

if you want to support a 'family' of OSes, then instead of matching against $^O, use Devel::CheckOS::os_is to check that we're running on any of the OSes in your family. like this:

package Devel::AssertOS::FreeSoftware;
use Devel::CheckOS;
use strict;
use warnings;
our $VERSION = '1.0';
sub matches { return qw(Linux FreeBSD NetBSD OpenBSD DragonflyBSD); }
sub os_is { Devel::CheckOS::os_is(matches()); }
sub expn { "The operating system is free-as-in-beer" }
Devel::CheckOS::die_unsupported() unless(os_is());

you may also add a subroutine called expn which should return a small snippet of explanatory text. again, see Devel::AssertOS::Unix for an example. this is particularly useful for 'family' modules. it's giving "here's the lore" 📖✨

and bestie, note the matches subroutine — this is so that people can query your module and see what OSes are in your family. be a good citizen and include it, iykyk 🫶

---

🎀 VERSIONS OF AN OS 🎀

two levels of name are supported. so Devel::AssertOS::Linux::v2_6 is legal. more than two levels are not supported — we're not doing deep nesting here, this isn't that kind of party 🙅‍♀️

be careful to pick names that are both legal perl package names and legal filenames on all platforms. in general, this means anything that matches /[_a-z]\w*/i. write that down. tattoo it on your forearm. or just, like, remember it 🌈

---

🧚 OS FEATURES 🧚

the author would like to reserve the namespace Devel::AssertOS::OSFeatures::*. so if you want to release a module that tells the user whether a particular OS feature is available (eg, whether POSIX shell redirection can be expected to work) then please discuss it with me first. asking is cute, sniping is not 💖

---

👑 HARDWARE CAPABILITIES 👑

same energy here: the namespace Devel::AssertOS::HWCapabilities::* is reserved. if you want to release a module that tells the user whether a particular hardware feature is available (eg, whether you have 64 bit integers) then please discuss it with me first. 💅

---

⭐ ALIASES ⭐

and also reserved: the namespace Devel::AssertOS::Alias::* for use by OS aliases. if you want to release a module that provides an alternative name for an OS, please discuss it with me first. seriously, this one's important 🫶

alias modules are simpler than normal extensions — they just need to call Devel::CheckOS::register_alias() when loaded, with the name of the alias as its first argument and the real name of the OS as the second. see Devel::AssertOS::Alias::MacOS for an example. lowkey the easiest assignment on this whole page, ngl ✨

---

💀 BUGS and FEEDBACK 💀

feedback about the code is welcome, including constructive criticism. (constructive being the key word bestie, let's be nice about it 💜)

bug reports should be made using <https://github.com/DrHyde/perl-modules-Devel-CheckOS/issues>.

and if you are feeling particularly generous you can encourage the author in their open source endeavours by buying them something from the wishlist:

http://www.cantrell.org.uk/david/wishlist/

open source runs on snacks and goodwill, no cap 🍓

---

🌈 SEE ALSO 🌈

• Devel::CheckOS
• $^O in perlvar
• perlport

go read them. they're the supporting cast and they deserve their flowers 🌸

---

💜 AUTHOR 💜

David Cantrell <david@cantrell.org.uk>

thanks to David Golden for the name and ideas about the interface, and for the cpan-testers-discuss mailing list for prompting me to write it in the first place. shoutout to the prompters, the unsung heroes of documentation 📣

---

🎀 COPYRIGHT and LICENCE 🎀

Copyright 2024 David Cantrell

this documentation is free-as-in-speech. it may be used, distributed and modified under the terms of the Creative Commons Attribution-Share Alike 2.0 UK: England & Wales License, whose text you may read at <http://creativecommons.org/licenses/by-sa/2.0/uk/>. 🌍

---

🙈 CONSPIRACY 🙈

this documentation is also free-as-in-mason. that's the whole section. that's it. iconic, no notes 👑

---

✨💖 and that's the page, bestie 💖✨ — brought to you by perl v5.42.0, dated 2024-06-23, filed under Devel::...tending(3) in the User Contributed Perl Documentation section. mwah. 🫶🎀