libcueify 0.5.0
---------------

libcueify is a library which permits access to a vast variety of Audio
CD metadata, including Table of Contents (TOC) data, multi-session
data, and CD-TEXT data.

libcueify requires:

- cmake (>= 2.6) <http://www.cmake.org/>

For unit tests (make check), libcueify additionally requires:

- check <http://check.sourceforge.net/>
- SWIG <http://www.swig.org/>
- Python development libraries <http://www.python.org/>

libcueify has been tested (and compiles) with the following configurations:

- Linux
- FreeBSD
- Darwin (Mac OS X)
- Cygwin
- MinGW (libcheck tests cannot be run)

It likely requires little modification to work with Visual Studio directly.

BUILDING:

The Makefile (for use with GNU Make) included provides some simple
targets to control building with cmake, including the targets you'd
expect ("all", "check", "install", "clean", "distclean", "docs"),
simply creating the subdirectory "build" to contain compiler output.
However, you may use cmake to generate the build directory somewhere
other than a subdirectory named "build".  Thus, simply invoking "make"
will configure and compile libcueify.

If you are building using MinGW (particularly, MSYS), the Makefile
assumes that you have CMake installed in "C:\Program Files\CMake
2.8\bin\cmake.exe".  You will need to modify the Makefile if this is
not the case.

TESTING:

In addition to the "check" target, which tests the library internal
APIs, the "check-unportable", "check-indices" and "check-pregaps"
targets will run additional tests on the unportable APIs which make
use of direct access to the CD-ROM drive, with some assumptions as to
the disc that's currently in the drive.  Since these tests aren't
easily reproduced without the right disc, they are not run
automatically via "make check".

LANGUAGE BINDINGS:

libcueify is written in C, but bindings for other languages have been
provided, including:

- C++
- Perl
- Python
- Ruby (requires rake, rubygems, and rake-compiler)

C++ bindings are made available through the wrapper header
libcueify/cueify.hxx.

Perl, Python, and Ruby, on the other hand, are provided by way of SWIG
(http://www.swig.org/), which is required in order to generate the
wrapper libraries for these scripting languages.

SWIG >= 1.3.40 is required to compile the bindings for Perl, Python,
and Ruby (>= 2.0.1 for Ruby 1.9.0+), and bindings may be compiled by
invoking the language appropriate installation method for each
language after libcueify has been installed:

- Perl:
  "make perl-cueify; cd build/swig/perl; perl Makefile.PL; make; make install"
  (as with other Perl extensions; note that make perl-cueify must be
  called first to generate Makefile.PL in build/swig/perl and the
  appropriate PM files in build/swig/perl.)
- Python: "python ./setup.py" (as with other Python extensions)
- Ruby: "rake native gem" (generates a native gem in the pkg/ directory)

Please note that the rubygem created for the Ruby extension may then
be installed as any other rubygem.  If need be, the prefix in which
libcueify was installed may be specified for Ruby by calling "rake
native gem -- --with-cueify-dir=<PREFIX>" as you would with a normal
extconf.rb.

The APIs in these languages follow the same design as the C++
bindings, with some caveats:

- Most getters aside from the cueify::Device.read*() functions are
  implemented as properties or attributes, rather than functions on
  the objects and return appropriate data-types. (e.g. std::vectors
  become language-specific array types, std::strings become strings)

- Where possible (mostly in Ruby), names of constants, classes, and
  methods have been renamed to match standard practice within the
  language (e.g. in Ruby, Device.readCDText() becomes
  Device::read_cdtext() and the hasTitle() getter becomes
  "has_title?")

- The nested classes of the C++ API are, due to limitations of SWIG,
  flattened into the global Cueify namespace by removing the
  double-colons.  (e.g. the class cueify::CDText::TOC::Track::Interval
  is cueify.CDTextTOCTrackInterval in Python)

NOTES:

Some calls in some OSs use SCSI pass-through logic, and as such, may
misbehave on older drives which don't support the SCSI commands used
(Specifically, READ TOC/PMA/ATIP with CD-Text support and READ CD with
subchannel read support).  Furthermore, I have not tested this code
with any IDE/ATAPI drives, so I am unsure whether these SCSI commands
will work correctly with them either.

libcueify should support CDs with CD-TEXT in the Japanese MS-JIS
encoding.  However, this encoding has been reverse engineered without
the use of the Music Shift-JIS standard itself, and, as far as I am
aware, has never been used on an actual retail disc; as a result this
support has not been tested.  Furthermore, some non-Unicode variation
selectors will be output when converting to UTF-8 (in order to support
round-trip encoding).