Debian Codegraph @

upstream/mageia-cauldron/man3pm/ExtUtils::Constant.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "ExtUtils::Constant 3pm"
61 .TH ExtUtils::Constant 3pm 2023-12-22 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 ExtUtils::Constant \- generate XS code to import C header constants
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 7
71 \& use ExtUtils::Constant qw (WriteConstants);
72 \& WriteConstants(
73 \& NAME => \*(AqFoo\*(Aq,
74 \& NAMES => [qw(FOO BAR BAZ)],
75 \& );
76 \& # Generates wrapper code to make the values of the constants FOO BAR BAZ
77 \& # available to perl
78 .Ve
79 .SH DESCRIPTION
80 .IX Header "DESCRIPTION"
81 ExtUtils::Constant facilitates generating C and XS wrapper code to allow
82 perl modules to AUTOLOAD constants defined in C library header files.
83 It is principally used by the \f(CW\*(C`h2xs\*(C'\fR utility, on which this code is based.
84 It doesn\*(Aqt contain the routines to scan header files to extract these
85 constants.
86 .SH USAGE
87 .IX Header "USAGE"
88 Generally one only needs to call the \f(CW\*(C`WriteConstants\*(C'\fR function, and then
89 .PP
90 .Vb 1
91 \& #include "const\-c.inc"
92 .Ve
93 .PP
94 in the C section of \f(CW\*(C`Foo.xs\*(C'\fR
95 .PP
96 .Vb 1
97 \& INCLUDE: const\-xs.inc
98 .Ve
99 .PP
100 in the XS section of \f(CW\*(C`Foo.xs\*(C'\fR.
101 .PP
102 For greater flexibility use \f(CWconstant_types()\fR, \f(CW\*(C`C_constant\*(C'\fR and
103 \&\f(CW\*(C`XS_constant\*(C'\fR, with which \f(CW\*(C`WriteConstants\*(C'\fR is implemented.
104 .PP
105 Currently this module understands the following types. h2xs may only know
106 a subset. The sizes of the numeric types are chosen by the \f(CW\*(C`Configure\*(C'\fR
107 script at compile time.
108 .IP IV 4
109 .IX Item "IV"
110 signed integer, at least 32 bits.
111 .IP UV 4
112 .IX Item "UV"
113 unsigned integer, the same size as \fIIV\fR
114 .IP NV 4
115 .IX Item "NV"
116 floating point type, probably \f(CW\*(C`double\*(C'\fR, possibly \f(CW\*(C`long double\*(C'\fR
117 .IP PV 4
118 .IX Item "PV"
119 NUL terminated string, length will be determined with \f(CW\*(C`strlen\*(C'\fR
120 .IP PVN 4
121 .IX Item "PVN"
122 A fixed length thing, given as a [pointer, length] pair. If you know the
123 length of a string at compile time you may use this instead of \fIPV\fR
124 .IP SV 4
125 .IX Item "SV"
126 A \fBmortal\fR SV.
127 .IP YES 4
128 .IX Item "YES"
129 Truth. (\f(CW\*(C`PL_sv_yes\*(C'\fR) The value is not needed (and ignored).
130 .IP NO 4
131 .IX Item "NO"
132 Defined Falsehood. (\f(CW\*(C`PL_sv_no\*(C'\fR) The value is not needed (and ignored).
133 .IP UNDEF 4
134 .IX Item "UNDEF"
135 \&\f(CW\*(C`undef\*(C'\fR. The value of the macro is not needed.
136 .SH FUNCTIONS
137 .IX Header "FUNCTIONS"
138 .IP constant_types 4
139 .IX Item "constant_types"
140 A function returning a single scalar with \f(CW\*(C`#define\*(C'\fR definitions for the
141 constants used internally between the generated C and XS functions.
142 .IP "XS_constant PACKAGE, TYPES, XS_SUBNAME, C_SUBNAME" 4
143 .IX Item "XS_constant PACKAGE, TYPES, XS_SUBNAME, C_SUBNAME"
144 A function to generate the XS code to implement the perl subroutine
145 \&\fIPACKAGE\fR::constant used by \fIPACKAGE\fR::AUTOLOAD to load constants.
146 This XS code is a wrapper around a C subroutine usually generated by
147 \&\f(CW\*(C`C_constant\*(C'\fR, and usually named \f(CW\*(C`constant\*(C'\fR.
148 .Sp
149 \&\fITYPES\fR should be given either as a comma separated list of types that the
150 C subroutine \f(CW\*(C`constant\*(C'\fR will generate or as a reference to a hash. It should
151 be the same list of types as \f(CW\*(C`C_constant\*(C'\fR was given.
152 [Otherwise \f(CW\*(C`XS_constant\*(C'\fR and \f(CW\*(C`C_constant\*(C'\fR may have different ideas about
153 the number of parameters passed to the C function \f(CW\*(C`constant\*(C'\fR]
154 .Sp
155 You can call the perl visible subroutine something other than \f(CW\*(C`constant\*(C'\fR if
156 you give the parameter \fIXS_SUBNAME\fR. The C subroutine it calls defaults to
157 the name of the perl visible subroutine, unless you give the parameter
158 \&\fIC_SUBNAME\fR.
159 .IP "autoload PACKAGE, VERSION, AUTOLOADER" 4
160 .IX Item "autoload PACKAGE, VERSION, AUTOLOADER"
161 A function to generate the AUTOLOAD subroutine for the module \fIPACKAGE\fR
162 \&\fIVERSION\fR is the perl version the code should be backwards compatible with.
163 It defaults to the version of perl running the subroutine. If \fIAUTOLOADER\fR
164 is true, the AUTOLOAD subroutine falls back on AutoLoader::AUTOLOAD for all
165 names that the \fBconstant()\fR routine doesn\*(Aqt recognise.
166 .IP WriteMakefileSnippet 4
167 .IX Item "WriteMakefileSnippet"
168 WriteMakefileSnippet ATTRIBUTE => VALUE [, ...]
169 .Sp
170 A function to generate perl code for Makefile.PL that will regenerate
171 the constant subroutines. Parameters are named as passed to \f(CW\*(C`WriteConstants\*(C'\fR,
172 with the addition of \f(CW\*(C`INDENT\*(C'\fR to specify the number of leading spaces
173 (default 2).
174 .Sp
175 Currently only \f(CW\*(C`INDENT\*(C'\fR, \f(CW\*(C`NAME\*(C'\fR, \f(CW\*(C`DEFAULT_TYPE\*(C'\fR, \f(CW\*(C`NAMES\*(C'\fR, \f(CW\*(C`C_FILE\*(C'\fR and
176 \&\f(CW\*(C`XS_FILE\*(C'\fR are recognised.
177 .IP "WriteConstants ATTRIBUTE => VALUE [, ...]" 4
178 .IX Item "WriteConstants ATTRIBUTE => VALUE [, ...]"
179 Writes a file of C code and a file of XS code which you should \f(CW\*(C`#include\*(C'\fR
180 and \f(CW\*(C`INCLUDE\*(C'\fR in the C and XS sections respectively of your module\*(Aqs XS
181 code. You probably want to do this in your \f(CW\*(C`Makefile.PL\*(C'\fR, so that you can
182 easily edit the list of constants without touching the rest of your module.
183 The attributes supported are
184 .RS 4
185 .IP NAME 4
186 .IX Item "NAME"
187 Name of the module. This must be specified
188 .IP DEFAULT_TYPE 4
189 .IX Item "DEFAULT_TYPE"
190 The default type for the constants. If not specified \f(CW\*(C`IV\*(C'\fR is assumed.
191 .IP BREAKOUT_AT 4
192 .IX Item "BREAKOUT_AT"
193 The names of the constants are grouped by length. Generate child subroutines
194 for each group with this number or more names in.
195 .IP NAMES 4
196 .IX Item "NAMES"
197 An array of constants\*(Aq names, either scalars containing names, or hashrefs
198 as detailed in "C_constant".
199 .IP PROXYSUBS 4
200 .IX Item "PROXYSUBS"
201 If true, uses proxy subs. See ExtUtils::Constant::ProxySubs.
202 .IP C_FH 4
203 .IX Item "C_FH"
204 A filehandle to write the C code to. If not given, then \fIC_FILE\fR is opened
205 for writing.
206 .IP C_FILE 4
207 .IX Item "C_FILE"
208 The name of the file to write containing the C code. The default is
209 \&\f(CW\*(C`const\-c.inc\*(C'\fR. The \f(CW\*(C`\-\*(C'\fR in the name ensures that the file can\*(Aqt be
210 mistaken for anything related to a legitimate perl package name, and
211 not naming the file \f(CW\*(C`.c\*(C'\fR avoids having to override Makefile.PL\*(Aqs
212 \&\f(CW\*(C`.xs\*(C'\fR to \f(CW\*(C`.c\*(C'\fR rules.
213 .IP XS_FH 4
214 .IX Item "XS_FH"
215 A filehandle to write the XS code to. If not given, then \fIXS_FILE\fR is opened
216 for writing.
217 .IP XS_FILE 4
218 .IX Item "XS_FILE"
219 The name of the file to write containing the XS code. The default is
220 \&\f(CW\*(C`const\-xs.inc\*(C'\fR.
221 .IP XS_SUBNAME 4
222 .IX Item "XS_SUBNAME"
223 The perl visible name of the XS subroutine generated which will return the
224 constants. The default is \f(CW\*(C`constant\*(C'\fR.
225 .IP C_SUBNAME 4
226 .IX Item "C_SUBNAME"
227 The name of the C subroutine generated which will return the constants.
228 The default is \fIXS_SUBNAME\fR. Child subroutines have \f(CW\*(C`_\*(C'\fR and the name
229 length appended, so constants with 10 character names would be in
230 \&\f(CW\*(C`constant_10\*(C'\fR with the default \fIXS_SUBNAME\fR.
231 .RE
232 .RS 4
233 .RE
234 .SH AUTHOR
235 .IX Header "AUTHOR"
236 Nicholas Clark <[email protected]> based on the code in \f(CW\*(C`h2xs\*(C'\fR by Larry Wall and
237 others