NAME
Alien::Libjio - Utility package to install and locate libjio
VERSION
Version 1.0.4 ($Id: Libjio.pm 8251 2009-07-27 03:10:41Z FREQUENCY@cpan.org $)
DESCRIPTION
To ensure reliability, some file systems and databases provide support for something known as journalling. The idea is to ensure data consistency by creating a log of actions to be taken (called a Write Ahead Log) before committing them to disk. That way, if a transaction were to fail due to a system crash or other unexpected event, the write ahead log could be used to finish writing the data.
While this functionality is often available with networked databases, it can be a rather memory- and processor-intensive solution, even where reliable writes are important. In other cases, the filesystem does not provide native journalling support, so other tricks may be used to ensure data integrity, such as writing to a separate temporary file and then overwriting the file instead of modifying it in-place. Unfortunately, this method cannot handle threaded operations appropriately.
Thankfully, Alberto Bertogli published a userspace C library called libjio that can provide these features in a small (less than 1500 lines of code) library with no external dependencies.
This package is designed to install it, and provide a way to get the flags necessary to compile programs using it. It is particularly useful for Perl XS programs that use it, such as IO::Journal.
SYNOPSIS
use Alien::Libjio;
my $jio = Alien::Libjio->new;
my $ldflags = $jio->ldflags;
my $cflags = $jio->cflags;COMPATIBILITY
This module was tested under Perl 5.10.0, using Debian Linux. However, because it's Pure Perl and doesn't do anything too obscure, it should be compatible with any version of Perl that supports its prerequisite modules.
By default, this library is installed wherever the main system libraries are usually installed. As a result, Alien::Libjio will only work if installed with root permissions.
If you encounter any problems on a different version or architecture, please contact the maintainer.
METHODS
Alien::Libjio->new
Creates a new Alien::Libjio object, which essentially just has a few convenience methods providing useful information like compiler and linker flags.
Example code:
my $jio = Alien::Libjio->new();This method will return an appropriate Alien::Libjio object or throw an exception on error.
$jio->installed
Determine if a valid installation of libjio has been detected in the system. This method will return a true value if it is, or undef otherwise.
Example code:
print "okay\n" if $jio->installed;$jio->version
Determine the installed version of libjio, as a string.
Currently versions are simply floating-point numbers, so you can treat the version number as such, but this behaviour is subject to change.
Example code:
my $version = $jio->version;$jio->ldflags
$jio->linker_flags
This returns the flags required to link C code with the local installation of libjio (typically in the LDFLAGS variable). It is particularly useful for building and installing Perl XS modules such as IO::Journal.
In scalar context, it returns an array reference suitable for passing to other build systems, particularly Module::Build. In list context, it gives a normal array so that join and friends will work as expected.
Example code:
my $ldflags = $jio->ldflags;
my @ldflags = @{ $jio->ldflags };
my $ldstring = join(' ', $jio->ldflags);
# or:
# my $ldflags = $jio->linker_flags;$jio->cflags
$jio->compiler_flags
This method returns the compiler option flags to compile C code which uses the libjio library (typically in the CFLAGS variable). It is particularly useful for building and installing Perl XS modules such as IO::Journal.
Example code:
my $cflags = $jio->cflags;
my @cflags = @{ $jio->cflags };
my $ccstring = join(' ', $jio->cflags);
# or:
# my $cflags = $jio->compiler_flags;$jio->method
$jio->how
This method returns the method the module used to find information about libjio. The following methods are currently used (in priority order):
pkg-config: the de-facto package information tool
ExtUtils::Liblist: a utility module used by ExtUtils::MakeMaker
Example code:
if ($jio->installed) {
print 'I found this information using: ', $jio->how, "\n";
}AUTHOR
Jonathan Yu <frequency@cpan.org>
CONTRIBUTORS
Your name here ;-)
ACKNOWLEDGEMENTS
Special thanks to Alberto Bertogli <albertito@blitiri.com.ar> for developing this useful library and for releasing it into the public domain.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Alien::LibjioYou can also look for information at:
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
CPAN Request Tracker
CPAN Testing Service (Kwalitee Tests)
CPAN Testers Platform Compatibility Matrix
REPOSITORY
You can access the most recent development version of this module at:
http://svn.ali.as/cpan/trunk/Alien-Libjio
If you are a CPAN developer and would like to make modifications to the code base, please contact Adam Kennedy <adamk@cpan.org>, the repository administrator. I only ask that you contact me first to discuss the changes you wish to make to the distribution.
FEEDBACK
Please send relevant comments, rotten tomatoes and suggestions directly to the maintainer noted above.
If you have a bug report or feature request, please file them on the CPAN Request Tracker at http://rt.cpan.org. If you are able to submit your bug report in the form of failing unit tests, you are strongly encouraged to do so.
SEE ALSO
IO::Journal, a Perl module that provides an interface to libjio.
http://blitiri.com.ar/p/libjio/, Alberto Bertogli's page about libjio, which explains the purpose and features of libjio.
CAVEATS
KNOWN BUGS
There are no known bugs as of this release.
LIMITATIONS
This module can only search known/common paths for libjio installations. It does try to use pkg-config and ExtUtils::Liblist to find a libjio installation on your system, but it cannot predict where files might have been installed. As a result, this package might install a duplicate copy of libjio.
There is currently no way to save a custom library installation path for libjio. This is likely to change in the future.
pkg-config may fail if you have an insecure $ENV{PATH} variable. Due to the way IPC::Open3 works, taintedness exceptions are suppressed and pkg-config seems to fail for no reason. The recommended fix for this is to use a module like Env::Sanctify::Auto or to otherwise clean up the calling environment. Another workaround is to disable taint checking, but that's not recommended. (See: http://rt.perl.org/rt3/Ticket/Display.html?id=66572)
LICENSE
In a perfect world, I could just say that this package and all of the code it contains is Public Domain. It's a bit more complicated than that; you'll have to read the included LICENSE file to get the full details.
QUALITY ASSURANCE METRICS
TEST COVERAGE
----------------------- ------ ------ ------ ------ ------ ------
File stmt bran cond sub pod total
----------------------- ------ ------ ------ ------ ------ ------
Alien/Libjio.pm 98.9 87.5 66.7 100.0 100.0 94.9Okay, granted, the coverage sucks -- generally, I aim for 100% in all of the categories, using fault injection to test all the code paths. Due to the nature of the module it's somewhat difficult to do.
DISCLAIMER OF WARRANTY
The software is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.