1Devel::AssertOS::ExtendUisnegr(3C)ontributed Perl DocumeDnetvaetli:o:nAssertOS::Extending(3)
2
6 Devel::AssertOS::Extending - how to write Devel::AssertOS::* modules
7 that check what platform they're running on
8
10 Devel::AssertOS::* modules are used by Devel::CheckOS to figure out
11 what OS it is running on. A set of modules are provided which should
12 correctly detect all platforms that perl *currently* runs on, as well
13 as detecting OS 'families' like 'Unix' and 'Windows'.
14 You can also use Devel::AssertOS::* modules on their own to quickly
16 check whether you're running on the right platform.
17 If you try to "use" a Devel::AssertOS module on the wrong platform, it
19 will "die" by calling Devel::CheckOS::die_unsupported(). This
20 conveniently spits out the text that CPAN-testers look for to see if
21 your code failed simply because they're doing something as silly as
22 testing your Solaris-only code on HPUX.
23
25 If you want to add support for new platforms, you need to write a
26 module called Devel::AssertOS::PlatformName which looks like:
27 package Devel::AssertOS::Linux;
29 use Devel::CheckOS;
30 use strict;
31 use warnings;
32 no warnings 'redefine';
33 our $VERSION = '1.0';
34 sub os_is { $^O =~ /^linux$/i ? 1 : 0; }
35 Devel::CheckOS::die_unsupported() unless(os_is());
36 1;
37 And that's it. The subroutine must be called "os_is" and loading the
39 module must die in precisely that manner if your code is running on the
40 wrong platform. It's a good idea to check $^O case-insensitively as
41 it's not consistent. Note that it is an error to say:
42 sub os_is { 1; }
44 and assume "well, on the wrong platform that'll never get reached
46 because the module can't load". Because the module *can* load, and
47 indeed *does get loaded* - some functions in Devel::CheckOS do things
48 like:
49 eval "use Devel::AssertOS::$os";
51 to suppress the error.
53 If you want to support a 'family' of OSes, then instead of matching
55 against $^O, instead use "Devel::CheckOS::os_is" to check that we're
56 running on any of the OSes in your family, like this:
57 package Devel::AssertOS::FreeSoftware;
59 use Devel::CheckOS;
60 use strict;
61 use warnings;
62 our $VERSION = '1.0';
63 sub matches { return qw(Linux FreeBSD NetBSD OpenBSD DragonflyBSD); }
64 sub os_is { Devel::CheckOS::os_is(matches()); }
65 sub expn { "The operating system is free-as-in-beer" }
66 Devel::CheckOS::die_unsupported() unless(os_is());
67 You may also add a subroutine called "expn" which should return a small
69 snippet of explanatory text. Again, see Devel::AssertOS::Unix for an
70 example. This is particularly useful for 'family' modules.
71 Note the "matches" subroutine - this is so that people can query your
73 module and see what OSes are in your family.
74
76 Two levels of name are supported. So "Devel::AssertOS::Linux::v2_6" is
77 legal. More than two levels are not supported. Be careful to pick
78 names that are both legal perl package names and legal filenames on all
79 platforms. In general, this means anything that matches
80 "/[_a-z]\w*/i".
81
83 I would like to reserve the namespace "Devel::AssertOS::OSFeatures::*".
84 If you want to release a module that tells the user whether a
85 particular OS feature is available (eg, whether POSIX shell redirection
86 can be expected to work) then please discuss it with me first.
87
89 I would like to reserve the namespace
90 "Devel::AssertOS::HWCapabilities::*". If you want to release a module
91 that tells the user whether a particular hardware feature is available
92 (eg, whether you have 64 bit integers) then please discuss it with me
93 first.
94
96 I would like to reserve the namespace "Devel::AssertOS::Alias::*" for
97 use by OS aliases. If you want to release a module that provides an
98 alternative name for an OS please discuss it with me first.
99 Alias modules are simpler than normal extensions, they just need to
101 call Devel::CheckOS::register_alias() when loaded, with the name of the
102 alias as its first argument and the real name of the OS as the second.
103 See Devel::AssertOS::Alias::MacOS for an example.
104
106 I welcome feedback about my code, including constructive criticism.
107 Bug reports should be made using
108 <https://github.com/DrHyde/perl-modules-Devel-CheckOS/issues>.
109 If you are feeling particularly generous you can encourage me in my
111 open source endeavours by buying me something from my wishlist:
112 <http://www.cantrell.org.uk/david/wishlist/>
113
115 Devel::CheckOS
116 $^O in perlvar
118 perlport
120
122 David Cantrell <david@cantrell.org.uk>
123 Thanks to David Golden for the name and ideas about the interface, and
125 for the cpan-testers-discuss mailing list for prompting me to write it
126 in the first place.
127
129 Copyright 2023 David Cantrell
130 This documentation is free-as-in-speech. It may be used, distributed
132 and modified under the terms of the Creative Commons Attribution-Share
133 Alike 2.0 UK: England & Wales License, whose text you may read at
134 <http://creativecommons.org/licenses/by-sa/2.0/uk/>.
135
137 This documentation is also free-as-in-mason.
138perl v5.38.0 2023-07-20 Devel::AssertOS::Extending(3)