1Devel::AssertOS::ExtendUisnegr(3C)ontributed Perl DocumeDnetvaetli:o:nAssertOS::Extending(3)
2
3
4

NAME

6       Devel::AssertOS::Extending - how to write Devel::AssertOS::* modules
7       that check what platform they're running on
8

DESCRIPTION

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
15       You can also use Devel::AssertOS::* modules on their own to quickly
16       check whether you're running on the right platform.
17
18       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

HOW TO WRITE YOUR OWN MODULES

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
28           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
38       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
43           sub os_is { 1; }
44
45       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
50           eval "use Devel::AssertOS::$os";
51
52       to suppress the error.
53
54       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
58       match any of several values of $^O like this:
59
60           package Devel::AssertOS::FreeSoftware;
61           use Devel::CheckOS;
62           use strict;
63           use warnings;
64           our $VERSION = '1.0';
65           sub matches { return qw(Linux FreeBSD NetBSD OpenBSD DragonflyBSD); }
66           sub os_is { Devel::CheckOS::os_is(matches()); }
67           sub expn { "The operating system is free-as-in-beer" }
68           Devel::CheckOS::die_unsupported() unless(os_is());
69
70       You may also add a subroutine called "expn" which should return a small
71       snippet of explanatory text.  Again, see Devel::AssertOS::Unix for an
72       example.  This is particularly useful for 'family' modules.
73
74       Note the "matches" subroutine - this is so that people can query your
75       module and see what OSes are in your family.
76

VERSIONS OF AN OS

78       Two levels of name are supported.  So "Devel::AssertOS::Linux::v2_6" is
79       legal.  More than two levels are not supported.  Be careful to pick
80       names that are both legal perl package names and legal filenames on all
81       platforms.  In general, this means anything that matches
82       "/[_a-z]\w*/i".
83

OS FEATURES

85       I would like to reserve the namespace "Devel::AssertOS::OSFeatures::*".
86       If you want to release a module that tells the user whether a
87       particular feature is available (eg, whether POSIX shell redirection
88       can be expected to work) then please discuss it with me first.
89

BUGS and FEEDBACK

91       I welcome feedback about my code, including constructive criticism.
92       Bug reports should be made using
93       <https://github.com/DrHyde/perl-modules-Devel-CheckOS/issues>.
94
95       If you are feeling particularly generous you can encourage me in my
96       open source endeavours by buying me something from my wishlist:
97         <http://www.cantrell.org.uk/david/wishlist/>
98

SEE ALSO

100       Devel::CheckOS
101
102       $^O in perlvar
103
104       perlport
105

AUTHOR

107       David Cantrell <david@cantrell.org.uk>
108
109       Thanks to David Golden for the name and ideas about the interface, and
110       for the cpan-testers-discuss mailing list for prompting me to write it
111       in the first place.
112

114       Copyright 2007 - 2014 David Cantrell
115
116       This documentation is free-as-in-speech.  It may be used, distributed
117       and modified under the terms of the Creative Commons Attribution-Share
118       Alike 2.0 UK: England & Wales License, whose text you may read at
119       <http://creativecommons.org/licenses/by-sa/2.0/uk/>.
120

CONSPIRACY

122       This documentation is also free-as-in-mason.
123
124
125
126perl v5.32.0                      2020-10-19     Devel::AssertOS::Extending(3)
Impressum