Device::Blkid::E2fsprogs version 0.26
=====================================

NOTE: This module only wraps the older e2fsprogs versions of libblkid (numbered 1.xx.x)
and not the newer versions now bundled as a part of util-linux-ng (v2.15 or better). In almost
every case you would be advised to use Bastian Friedrich's util-linux-ng based Device::Blkid
module as the newer lib interface is (mostly) backward compatible with the old one. This
module would prove useful in any situation where for any reason you are limited on your
systems to a 1.xx libblkid version which is a part of the e2fsprogs package. With respect to
version numbers, it is the convention that libblkid adopts a version number which matches the
package of which it is a part of, so when the library was migrated to the util-linux-ng package
it jumped in version number from 1.41.4 to 2.15. So the rule of thumb here is that if the
version of libblkid on your system begins with a '1', it is an e2fsprogs-based version of the
library, whereas those which begin with a '2' are the newer util-linux-ng based builds.
In most cases you are advised to use the newer Device::Blkid written by Bastian Friedrich
unless your are bound by some specific constraint to the e2fsprogs-based versions as I was,
which is what led me to create this package.

This version has been implemented somewhat differently than Bastian's util-linux-ng build
of the library. He opted to keep much of his logic and processing in XSUB, mine is done
mostly in C; I have only used XSUB for my straight glue, everything else I kept in C. This is
not to be taken as any opinion of statement on PerlXS/XSUB, its merely a reflection of my own
background and tastes.

This package provides a Perl interface to the e2fsprogs-based versions of libblkid. It does not
support the larger and more robust API which has been added and integrated into the libblkid
library since its inclusion in the util-linux-ng package. That said, the libblkid which now
ships with util-linux-ng is reportedly backward compatible with client code dependant upon the
older, original library which would mean that this module should work with it, albeit with the
more limited selection of API calls. Please see the preceding note for additional details.

Libblkid provides a means of identifying block devices as to their content (such as filesystems)
as well as allowing for the extraction of additional information such as filesystem labels,
volume labels, serial numbers, device numbers, unique identifiers, etc. The libblkid library
maintains a mapping of all of this composite information and maintains its association with
a given block device on the system. Libblkid is becoming more commonly seen in modern linux
distributions in places such as configuration files and other such places where hard coded
device names were once used.

In addition to providing for low level probing of block devices for this information, the
library maintains an on disk cache file of this data. It is by way of the cache file that
unpriviledged users are able to access this information via a variety of library calls. Use of
the cache file as opposed to direct, low level probing of the hardware is recommended whenever
possible and feasible.

Recognizing that this is a Perl module, I have tried to provide a more 'Perlish' interface
where possible rather than merely map Perl subs to C functions. Most library functions return
an undef on failure and a number of calls return hash types.

Please read the README file in the package archive for instructions should you encounter any
problems while using this software package, as well as for instructions on building a debug
version.

It is worth noting that between versions 1.33 and 1.41.4, the entire period which libblkid
was bundled as a part of the e2fsprogs package, the number of calls present in the API was
expanded from the 17 in the original release of the library back in 2003 to 25 when it was
migrated over to the util-linux-ng package in early 2009. This module supports all 24 calls
from the most recent iteration of this run. When users run the initial Makefile.PL script in
order to configure this package, it attempts to dynamically detect which version of the
libblkid library is currently installed on the target system and will generate a Makefile
which matches that target version. This version detection should work for any version of the
library after 1.35.  For versions 1.33 through to 1.35 there is the option to manually select
a build target for this package which should suit most needs. Finally, users may hand edit
the Makefile.PL script as needed to suit their specific needs.

E2FSPROGS-LIBBLKID VERSION HISTORY

Libblkid first appeared in version 1.33 of the e2fsprogs package back in 2003. The initial
release of the library exposed 17 function calls as part of its API. When libblkid stopped
shipping with the e2fsprogs package, the function count numbered at 25 calls which had been
the case since version 1.40 of the interface. A brief outline of the API history is as
follows:

   v1.33  -  17 calls
   v1.34  -  18 calls
   v1.36  -  21 calls
   v1.38  -  24 calls
   v1.40  -  25 calls

In version 1.36 of libblkid two functions appeared which returned version information about
the library, those were:

   int blkid_parse_version_string(const char *ver_string);
   int blkid_get_library_version(const char **ver_string, const char **date_string);
   
INSTALLATION

This module uses an optional dynamic libblkid version detection mechanism to try and ascertain
which version of libblkid is installed on the target system. It is optional and you are free to
select the libblkid version manually as well.  After running the standard, 'perl Makefile.PL',
please follow the in screen prompts for installation details. Please see the following sample
installation scenarios for further details.

This first scenario demonstrates a sample configuration and installation using the dynamic libblkid
library version detection.  Begin by running the Makefile.PL program, answering in the affirmative,
'Y/y' when asked to try the dynamic version detection, as follows:

  $ perl Makefile.PL

          Running Makefile.PL to perform package configuration.
          Would you like to try dynamic libblkid version detection and configuration?

          Y/y or N/n: y

          Version 1.40 or better of libblkid detected.
          Building module for that version

  Checking if your kit is complete...
  Looks good
  Writing Makefile for Device::Blkid::E2fsprogs

Here the dynamic version detection has successfully determined that version 1.40 or newer of
libblkid is installed on the target system and has written a Makefile which will generate a
matching module installation. Now that you have a Makefile which properly matches your version
of libblkid, the remainder of the build/install process is standard:
   
   make
   make test
   make install

This second scenario involves manual selection of a libblkid library version target and is
initiated by replying in the negative to the first question about dynamic version detection:

  $ perl Makefile.PL

          Running Makefile.PL to perform package configuration.
          Would you like to try dynamic libblkid version detection and configuration?

          Y/y or N/n: n                        
  
          The default is to build a v1.33 compliant interface as it will work with all e2fsprogs-based
          versions of libblkid. Keep in mind that attempting to build a version target which is more
          recent than the version which you have installed will fail with linker errors. If you are not
          entirely certain which version which you have installed, accepting the default here (a 'Y/y'
          selection) is safest, however you may wish to try the dynamic version detection which should
          accurately determine versions 1.36 and newer.

          If the default v1.33 build target is acceptable to you, please answer 'Y/y', otherwise select
          one of the following version bundles from the list, or 'Q/q' to quit:

          1. v1.36 (compliant with libblkid versions 1.36-1.37)
          2. v1.38 (compliant with libblkid versions 1.38-1.39)
          3. v1.40 (compliant with all libblkid versions better than 1.40)

          Enter selection (Y/y for default or option 1, 2, 3): 2

  Checking if your kit is complete...
  Looks good
  Writing Makefile for Device::Blkid::E2fsprogs

In this case the user has manually selected option 2, v1.38 of libblkid. This build target is
compliant with versions 1.38 and 1.39 of the library and a corresponding Makefile has been
generated which can now be run to build and install the target module. Again, this is done using
the standard make, make test, make install method:

  make
  make test
  make install

Finally, a third option is to edit the Makefile.PL directly for any custom requirements. Please see
that file for further details as it has been well documented.


===== libblkid version detection =====

I have made use of a customized Devel::CheckLib module and Makefile.PL in an attempt to detect
the version of libblkid currently installed on the target system and to then generate a PerlXS
interface which directly targets and matches the API interface of that libblkid version.

This process is expected to work on all versions of libblkid later than v1.35. Should you have
any problems with this process, evident either in running the Makefile.PL or in running make on
its resulting Makefile, please see the Makefile.PL as well as the E2fsprogs.xs file to troubleshoot.
If you wish to report any problems with this version detection, please include any output from the
installation process as well as a copy of your /usr/include/blkid/blkid.h file.
   
DEPENDENCIES

Perl 5.8.0

This module also requires these other modules and libraries:

E2fsprogs v1.33-v1.41

* Note: This package supports both dynamic version detection during the configuration phase
        of running Makefile.PL, as well as manual selection of a build target by version.
        If neither of these are suitable to your needs or there is some sort of problem with
        this on your target system, please refer to the Makefile.PL as well as Devel::CheckLib
        files; both are well documented and relatively easy to modify.

DEBUGGING and REPORTING A BUG

If you have any problems with the functioning of this library, please contact me at my CPAN
address at mroz@cpan.org. Please be sure and include a list of relevant packages installed on
your system or at least the exact version of e2fsprogs which you have installed, perhaps by
providing the blkid.h file.

Also, please build and install a DEBUG build of this module. The quickest way to generate a
DEBUG build of this package is by making a quick edit to the Makefile.PL file and uncommenting
the prefab DEFINE argument to the WriteMakefile() function call. Please refer to the details
on doing this found in the Makefile.PL file. After you have so configured your Makefile.PL,
run the initial configuration program as you would for a normal installation.

The DEBUG builds of this module generate a much higher degree of verbosity in output to STDOUT.
Please copy any output to STDOUT when you experience problems and be sure and include it in
any submission you send to me detailing your problem.

Furthermore, should you find any problems with this package and wish to submit a patch, please
send the unified diff to my CPAN address including full patch instructions as well as a
description of what issue or bug you have found and addressed. Please patch as per recommended
best practices found in the patch(1) man page, under "NOTES FOR PATCH SENDERS".
  
COPYRIGHT AND LICENCE

Copyright (C) 2010, 2011 by Raymond Mroz

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.10.1 or,
at your option, any later version of Perl 5 you may have available.

THANKS

Thanks to Bastian for all of is work on Device::Blkid, I was especially appreciative of your
POD as libblkid itself is not terribly well documented. While I did make a large number of my
own straight test calls in C against the library your documentation kept me in the right
direction and saved me a load of time. Thanks!

Thanks to David Cantrell, David Golden and Yasuhiro Matsumoto for Devel::CheckLib. I hacked it
up a little bit to manage my dynamic version checks and build, hope you don't mind.

I would also like to thank Larry McInnis for the loan of some hardware on which to develop this
module. Most everything I have had been tied up and developing on the latest and greatest version
of Debian didn't make much sense.

BUGS

No known bugs at this time. That said, this module is largely written in C and does contain
a number of memory allocations. While these allocations are done inside of the libblkid itself,
I do make every attempt to free the memory explicitly when I am done with it. That said, leaks
are possible. Report any issues as is detailed above.

FUTURE

Please note that this module should be considered early release. As such, this information or its
API may change at any time. Please check CPAN for the latest version of this software.
