1ExtUtils::Constant(3pm)Perl Programmers Reference GuideExtUtils::Constant(3pm)
2
3
4

NAME

6       ExtUtils::Constant - generate XS code to import C header constants
7

SYNOPSIS

9           use ExtUtils::Constant qw (WriteConstants);
10           WriteConstants(
11               NAME => 'Foo',
12               NAMES => [qw(FOO BAR BAZ)],
13           );
14           # Generates wrapper code to make the values of the constants FOO BAR BAZ
15           #  available to perl
16

DESCRIPTION

18       ExtUtils::Constant facilitates generating C and XS wrapper code to
19       allow perl modules to AUTOLOAD constants defined in C library header
20       files.  It is principally used by the "h2xs" utility, on which this
21       code is based.  It doesn't contain the routines to scan header files to
22       extract these constants.
23

USAGE

25       Generally one only needs to call the "WriteConstants" function, and
26       then
27
28           #include "const-c.inc"
29
30       in the C section of "Foo.xs"
31
32           INCLUDE: const-xs.inc
33
34       in the XS section of "Foo.xs".
35
36       For greater flexibility use "constant_types()", "C_constant" and
37       "XS_constant", with which "WriteConstants" is implemented.
38
39       Currently this module understands the following types. h2xs may only
40       know a subset. The sizes of the numeric types are chosen by the
41       "Configure" script at compile time.
42
43       IV  signed integer, at least 32 bits.
44
45       UV  unsigned integer, the same size as IV
46
47       NV  floating point type, probably "double", possibly "long double"
48
49       PV  NUL terminated string, length will be determined with "strlen"
50
51       PVN A fixed length thing, given as a [pointer, length] pair. If you
52           know the length of a string at compile time you may use this
53           instead of PV
54
55       SV  A mortal SV.
56
57       YES Truth.  ("PL_sv_yes")  The value is not needed (and ignored).
58
59       NO  Defined Falsehood.  ("PL_sv_no")  The value is not needed (and
60           ignored).
61
62       UNDEF
63           "undef".  The value of the macro is not needed.
64

FUNCTIONS

66       constant_types
67           A function returning a single scalar with "#define" definitions for
68           the constants used internally between the generated C and XS
69           functions.
70
71       XS_constant PACKAGE, TYPES, XS_SUBNAME, C_SUBNAME
72           A function to generate the XS code to implement the perl subroutine
73           PACKAGE::constant used by PACKAGE::AUTOLOAD to load constants.
74           This XS code is a wrapper around a C subroutine usually generated
75           by "C_constant", and usually named "constant".
76
77           TYPES should be given either as a comma separated list of types
78           that the C subroutine "constant" will generate or as a reference to
79           a hash. It should be the same list of types as "C_constant" was
80           given.  [Otherwise "XS_constant" and "C_constant" may have
81           different ideas about the number of parameters passed to the C
82           function "constant"]
83
84           You can call the perl visible subroutine something other than
85           "constant" if you give the parameter XS_SUBNAME. The C subroutine
86           it calls defaults to the name of the perl visible subroutine,
87           unless you give the parameter C_SUBNAME.
88
89       autoload PACKAGE, VERSION, AUTOLOADER
90           A function to generate the AUTOLOAD subroutine for the module
91           PACKAGE VERSION is the perl version the code should be backwards
92           compatible with.  It defaults to the version of perl running the
93           subroutine.  If AUTOLOADER is true, the AUTOLOAD subroutine falls
94           back on AutoLoader::AUTOLOAD for all names that the constant()
95           routine doesn't recognise.
96
97       WriteMakefileSnippet
98           WriteMakefileSnippet ATTRIBUTE => VALUE [, ...]
99
100           A function to generate perl code for Makefile.PL that will
101           regenerate the constant subroutines.  Parameters are named as
102           passed to "WriteConstants", with the addition of "INDENT" to
103           specify the number of leading spaces (default 2).
104
105           Currently only "INDENT", "NAME", "DEFAULT_TYPE", "NAMES", "C_FILE"
106           and "XS_FILE" are recognised.
107
108       WriteConstants ATTRIBUTE => VALUE [, ...]
109           Writes a file of C code and a file of XS code which you should
110           "#include" and "INCLUDE" in the C and XS sections respectively of
111           your module's XS code.  You probably want to do this in your
112           "Makefile.PL", so that you can easily edit the list of constants
113           without touching the rest of your module.  The attributes supported
114           are
115
116           NAME
117               Name of the module.  This must be specified
118
119           DEFAULT_TYPE
120               The default type for the constants.  If not specified "IV" is
121               assumed.
122
123           BREAKOUT_AT
124               The names of the constants are grouped by length.  Generate
125               child subroutines for each group with this number or more names
126               in.
127
128           NAMES
129               An array of constants' names, either scalars containing names,
130               or hashrefs as detailed in "C_constant".
131
132           PROXYSUBS
133               If true, uses proxy subs. See ExtUtils::Constant::ProxySubs.
134
135           C_FH
136               A filehandle to write the C code to.  If not given, then C_FILE
137               is opened for writing.
138
139           C_FILE
140               The name of the file to write containing the C code.  The
141               default is "const-c.inc".  The "-" in the name ensures that the
142               file can't be mistaken for anything related to a legitimate
143               perl package name, and not naming the file ".c" avoids having
144               to override Makefile.PL's ".xs" to ".c" rules.
145
146           XS_FH
147               A filehandle to write the XS code to.  If not given, then
148               XS_FILE is opened for writing.
149
150           XS_FILE
151               The name of the file to write containing the XS code.  The
152               default is "const-xs.inc".
153
154           XS_SUBNAME
155               The perl visible name of the XS subroutine generated which will
156               return the constants. The default is "constant".
157
158           C_SUBNAME
159               The name of the C subroutine generated which will return the
160               constants.  The default is XS_SUBNAME.  Child subroutines have
161               "_" and the name length appended, so constants with 10
162               character names would be in "constant_10" with the default
163               XS_SUBNAME.
164

AUTHOR

166       Nicholas Clark <nick@ccl4.org> based on the code in "h2xs" by Larry
167       Wall and others
168
169
170
171perl v5.34.1                      2022-03-15           ExtUtils::Constant(3pm)
Impressum