From 0f24424f357e854a9da382de11e4fe81305c8743 Mon Sep 17 00:00:00 2001 From: Richard Jones Date: Thu, 2 Sep 2010 10:58:28 +0100 Subject: [PATCH] perl: Add documentation about testing availability of methods and features. --- src/generator.ml | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/src/generator.ml b/src/generator.ml index 743118b..fcac9f8 100755 --- a/src/generator.ml +++ b/src/generator.ml @@ -9950,6 +9950,37 @@ the handle. =back +=head1 AVAILABILITY + +From time to time we add new libguestfs APIs. Also some libguestfs +APIs won't be available in all builds of libguestfs (the Fedora +build is full-featured, but other builds may disable features). +How do you test whether the APIs that your Perl program needs are +available in the version of C that you are using? + +To test if a particular function is available in the C +class, use the ordinary Perl UNIVERSAL method C +(see L). For example: + + use Sys::Guestfs; + if (defined (Sys::Guestfs->can (\"set_verbose\"))) { + print \"\\$h->set_verbose is available\\n\"; + } + +To test if particular features are supported by the current +build, use the L method like the example below. Note +that the appliance must be launched first. + + $h->available ( [\"augeas\"] ); + +Since the L method croaks if the feature is not supported, +you might also want to wrap this in an eval and return a boolean. +In fact this has already been done for you: use +L. + +For further discussion on this topic, refer to +L. + =head1 COPYRIGHT Copyright (C) %s Red Hat Inc. -- 1.8.3.1