NAME

Include - allow use #defines from C header files

SYNOPSIS

use Include qw(-I /some/path/of/mine);
use Include q<sys/types.h>;
use Include q<sys/types.h> "/[A-Z]/";

DESCRIPTION

The Include module implements a method of using #define constants from C header files. It does this by putting an extra level of indirection on the use operator.

To enhance performance a cache scheme is used. When a new module is required the cache is checked first, if the package is not found then it will be generated from the C header files.

Include can be configured to place any generated packages into the cache automatically, for security reasons this is turned off by default.

There are three ways in which the use Include statement can be used.

use Include qw(-I /some/path/of/mine);

Will unshift the directory /some/path/of/mine onto the search path used so that subsequent searches for .h header files will search the given directories first.

use Include q<sys/types.h>;
use Include q<sys/types.h> "/[A-Z]/";

Both of these will define all the constants found in <sys/types.h> and any header files included by it. The first will export all of these into the calling package, but the second will only export defined macros that contain an unppercase character.

Subroutines

Under normal use the Include package is only used via the use/import interface. But there are some routines that are defined.

CacheOn

This subroutine will cause the Include module to save any generated packages into the cache.

Generate( @headers )

This subroutine will force the generation of the given header files, and any files included in them, reguardless of whether they are currently in the cache. If cache writing is turned on then the cache files will be overwritten.

Search( @dirs )

This subroutine will unshift the given directories onto the search path used for locating the header files.

NOTE

Having the cache writing turned on by default if a potential security risk as all users will need write rights to the cache directory

AUTHOR

Graham Barr <Graham.Barr@tiuk.ti.com>

REVISION

$Revision: 1.2 $

BUGS

None known

COPYRIGHT

Parsing code is based on the h2ph program which comes with the perl distribution. All other code is Copyright (c) 1995 Graham Barr. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.