This module provides a way of using a module which may or may not be installed on the target machine. If the module is available it behaves as a straight use. If the module is not available, subs are repointed to their equivalents in a dummy namespace.

Suppose you are the developer of module Foo, which uses functionality from the highly controversial module Bar. You actually quite like Bar, and want to reuse its functionality in your Foo module. But, many people will refuse to install Foo as it needs Bar. Maybe Bar is failing tests or is misbehaving on some platforms.

Making Bar an optional module will allow users to run Foo that don't have Bar installed. For Module::Build users, this involves changing the status of the Bar dependency from requires to recommends.

To use this module, you need to set up a namespace Bar::Dummy. The recommended way of doing this is to ship lib/Bar/Dummy.pm with your module. This could be shipped as a standalone module. A dummy module for Params::Validate is shipped with Module::Optional, as this was the original motivation for the module. If there are other common candidates for dummying, petition me, and I'll include them in the Module::Optional distribution.

Always set up the dummy module first, but don't import anything - this is to avoid warnings about redefined subroutines if the real Bar is installed on the target machine. Module::Optional will do the importing: quux wibble and wobble from the real Bar if it exists, or from Bar::Dummy if it doesn't.

You will probably be developing your module on a platform that does have Bar installed (I hope). However, you need to be able to tell what happens on systems without Bar. To do this, run the following (example is Unix):

MODULE_OPTIONAL_SKIP=1 make test

You also want to do this in tests for the dummy module that you are providing. (You are providing tests for this module?) This can easily be done with a begin block at the top of the test:

You provide a namespace suffixed with ::Dummy containing subs corresponding to all the subs and method calls for the optional module. You should also provide the same exports as the module itself performs.

Adhere strictly to any prototypes in the optional module.

An example of a dummy module is Params::Validate::Dummy, provided in this distribution.