/ 
Devel-CheckOS-1.50
River stage three • 30 direct dependents • 359 total dependents
/ Devel::AssertOS::Extending

NAME

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

DESCRIPTION

Devel::AssertOS::* modules are used by Devel::CheckOS to figure out what OS it is running on. A set of modules are provided which should correctly detect all platforms that perl *currently* runs on, as well as detecting OS 'families' like 'Unix' and 'Windows'.

You can also use Devel::AssertOS::* modules on their own to quickly check whether you're running on the right platform.

If you try to use a Devel::AssertOS module on the wrong platform, it will die by calling Devel::CheckOS::die_unsupported(). This conveniently spits out the text that 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.

HOW TO WRITE YOUR OWN MODULES

If you want to add support for new platforms, you need to write a module called Devel::AssertOS::PlatformName which looks like:

package Devel::AssertOS::Linux;
use Devel::CheckOS;
$VERSION = '1.0';
sub os_is { $^O eq 'linux' ? 1 : 0; }
Devel::CheckOS::die_unsupported() unless(os_is());
1;

And that's it. 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.

If you want to support a 'family' of OSes, then change the subroutine to match any of several values of $^O like this:

package Devel::AssertOS::FreeSoftware;
...
sub os_is {
    $^O =~ /^(
        linux     |
        freebsd   |
        netbsd    |
        openbsd   |
        dragonfly
    )$/x ? 1 : 0;
}
...

Or you could make it a wrapper around several eval()ed 'use' statements to try all of Devel::AssertOS::Linux, Devel::AssertOS::FreeBSD etc in turn. See the sourcecode for Devel::AssertOS::Unix for an example.

You may also add a subroutine called expn which should return a small snipper of explanatory text. Again, see Devel::AssertOS::Unix for an example. This is particularly useful for 'family' modules.

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. 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.

OS FEATURES

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

BUGS and FEEDBACK

I welcome feedback about my code, including constructive criticism. Bug reports should be made using http://rt.cpan.org/ or by email.

If you are feeling particularly generous you can encourage me in my open source endeavours by buying me something from my wishlist: http://www.cantrell.org.uk/david/wishlist/

SEE ALSO

Devel::CheckOS

$^O in perlvar

perlport

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.

COPYRIGHT and LICENCE

Copyright 2007 - 2008 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.