The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
C-Scan-Constants-1.020
River stage one • 1 direct dependent • 2 total dependents
++
/ C::Scan::Constants

NAME

C::Scan::Constants - Slurp constants from specified C header (.h) files

VERSION

This documentation refers to C::Scan::Constants version 1.020.

SYNOPSIS

  ## Intended for use in your module's Makefile.PL file, to
  ## add DWIMery to use of C constants within your module.

  use C::Scan::Constants;

  my @hdr_files = (
      "/path/to/first_header.h",
      "/path/to/second_header.h",
  );

  ## Slurp a list of constant information from C headers
  my @constants = extract_constants_from( @hdr_files );

  ## Create the C, XS, and pure-Perl machinery needed to
  ## provide automagical access to C constants at runtime.
  write_constants_module( "Your::Module", @constants );

DESCRIPTION

This module provides an alternative to using the h2ph command to generate Perl header (.ph) files that are then subsequently required by your module code. When you need access to C numeric and enumerated type constants, especially in a dynamic source tree environment, there are times when you'd like something a little more automagical and closely tailored to what you actually need. Now you have it, in this module.

C::Scan::Constants was born out of a recognition that ModPerl::CScan and ExtUtils::Constant provide a wealth of capabilities in the area of C code parsing and autogenerated XS access to C constants, but that the actual mechanisms for harnessing them to do those things were really rather opaque. This module should help take (most of) the mystery out of those activities.

Here's a brief overview of the module:

  • Provides a function, "extract_constants_from()", that extracts a list of information relating to #define constants and "#typedef enum" style constants found in a supplied list of C header (.h) files.

  • Provides a function, "write_constants_module()", that generates three files:

            const-c.inc
        const-xs.inc
        lib/Your/ModuleName/Constants/C/Symbols.pm

    that are ready to be dropped into your module's build machinery to give your module runtime access to those constants.

  • Gives hints at perl Makefile.PL time about the code you need to add to files in your module's source tree to assure that all the tracks line up at module build time.

SUBROUTINES

The following two subroutines are exported by default.

@blobs = extract_constants_from( @header_paths )

    Takes a list of C header (.h) files and returns a list of constants information suitable for supplying as the NAME parameter to ExtUtils::Constant.

    Returns an array of constant name "blobs" suitable for feeding into ExtUtils::Constant::WriteConstants() as the value of the NAME parameter.

write_constants_module( $pkg_name, @c_constants )

    Writes a Constants/C/Symbols.pm submodule into the invoking Makefile.PL module's namespace. Really just a value-added wrapper around ExtUtils::Constant::WriteConstants().

    No return value -- call for side-effects only.

DIAGNOSTICS

TBD. I owe you a list of error and warning messages you might see when invoking functions from C::Scan::Constants.

CONFIGURATION AND ENVIRONMENT

TBD. If/when populated, this section will describe in detail how/where to add the necessary extra code to wire in the autogenerated files to your module. It will also describe what you need in your Makefile.PL to assure that the autogenerated stuff goes away at make clean time.

For the time being, write_constants_module() outputs to STDERR a number of hints that should provide the needed answers to these types of questions.

DEPENDENCIES

For the program proper:

    Carp, Data::Flow, ExtUtils::Constants, ModPerl::CScan, C::Scan, File::Temp, File::Copy, File::Spec, File::Path, Exporter

Additional modules needed for tests (over and above Test::More):

    Scalar::Util, List::MoreUtils, Cwd

COMPATIBILITY NOTES

This version of C::Scan::Constants is known to work with ExtUtil::Constants versions 0.14 - 0.16. It may not work properly with earlier or later versions. I welcome your comments and patches to assure continued compatibility going forward.

BUGS AND LIMITATIONS

The amount of code you are currently required to add to your module to make use of the files C::Scan::Constants generates seems rather too much. It would be highly useful to provide a more streamlined usage, or to provide scripts that would assist you in inserting the needed code into your module.

Also, the tests are incomplete. The runtime usability of constants generated by the module is not tested at all. I need to set up some tests that actually create a new module, invoke the C::Scan::Constants functionality, and then do a

    perl Makefile.PL
    make
    make test

regimen on that module in order to accomplish this. That's pretty tricky, so I haven't tackled it yet.

Finally (well probably not), it would be nice to be able to specify whether cpp should "follow" #include statements in C header files. Sometimes, that's what you really want. This version of C::Scan::Constants suppresses all such "following" behavior.

Other than that, there are no known bugs in this module.

Please report problems to Philip Monsen (philip.monsen@gmail.com). Patches are especially welcome.

AUTHOR

Philip Monsen (philip.monsen@gmail.com)

COPYRIGHT AND LICENSE

ModPerl::CScan

ModPerl::CScan is provided with this module for convenience for those users who do not wish to install mod_perl as a whole. This version is 0.75 from the mod_perl-2.0.1 distro.

Copyright (C) 2005 by Doug MacEachern.

Licensed under the Apache License, Version 2.0; you may not use this file except in compliance with the License. A current copy of the license is available at

     http://www.apache.org/licenses/LICENSE-2.0

See also contrib/LICENSE for a Jan. 2004 copy of the license text.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

All else

Copyright (C) 2005-11 by Philip Monsen.

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

This module is distributed in the hope that it will be useful, and is provided on an "AS-IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.