CONTENTS

1. DESCRIPTION
2. INSTALLATION
3. COMPATIBILITY
4. FEATURES
5. COPYRIGHT


--------------
1. DESCRIPTION
--------------

Convert::Binary::C is a preprocessor and parser for C type
definitions. It is highly configurable and should support
arbitrarily complex data structures. Its OO interface has pack
and unpack methods that act as replacements for Perl's pack
and unpack and allow to use the C types instead of a string
representation of the data structure for conversion of binary
data from and to Perl's complex data structures.

Actually, what Convert::Binary::C does is not very different
from what a C compiler does, just that it doesn't compile the
source code into an object file or executable, but only parses
the code and allows Perl to use the enumerations, structs and
typedefs that have been defined within your C source for binary
data conversion, similar to Perl's pack and unpack.

Beyond that, the module offers a lot of convenience methods
to retrieve information about the C types that have been parsed.

---------------
2. INSTALLATION
---------------

Installation of the Convert::Binary::C module follows the standard Perl way
and should not be harder than:

  perl Makefile.PL
  make
  make test
  make install

When running 'make test' on Windows and on slower systems be patient, since
the 'complex' and 'threads' tests may take quite some time.

Even on a 1 GHz machine, the whole test suite may need between 20 and 60
seconds to complete.

----------------
3. COMPATIBILITY
----------------

The module should build on most of the platforms that Perl runs on. I have
tested it on:

  - Linux
  - HP-UX
  - Windows 98/NT/2000

The module should build with any perl from 5.005_03 up to 5.8.0.

Multithreaded perl binaries are explicitly supported, as the module is
intended to be thread-safe.

-----------
4. FEATURES
-----------

You can enable or disable certain features at compile time by adding options
to the Makefile.PL call. However, you can safely leave them at their default.
Available features are 'debug' to build the module with debugging support,
'threads' to build a thread-safe version and 'c99' to build the module with
support for ANSI-C99 extensions. Note that the 'threads' feature is only
available for multithreaded perl binaries.

While 'c99' is enabled by default (and it makes little sense to disable it),
the 'threads' and 'debug' features depend on how your perl binary was built.
If it's built with the DEBUGGING flag, the 'debug' feature is enabled,
otherwise it's disabled by default. If your perl binary was built to support
threads, the module will be build thread-safe.

You can enable or disable features explicitly by adding the arguments

  enable-feature
  disable-feature

to the Makefile.PL call. To explicitly build the module with debugging enabled
and ANSI-C99 features disabled, you would say:

  perl Makefile.PL enable-debug disable-c99

This will still allow you to pass other 'standard' arguments to Makefile.PL.

------------
5. COPYRIGHT
------------

Copyright (c) 2002 Marcus Holland-Moritz. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

The ucpp library is (c) Thomas Pornin 1999, 2000. For licence
and redistribution details refer to 'ctlib/ucpp/README'.

Portions copyright (c) 1989, 1990 James A. Roskind.

Some of the include files used for the 't/parse.t' test
script are (c) 1991-1999, 2000, 2001 Free Software Foundation,
Inc. They are neither required to create the binary nor linked
to the source code of this module in any other way.