File: README

package info (click to toggle)
libextutils-cchecker-perl 0.04-1
  • links: PTS, VCS
  • area: main
  • in suites: squeeze
  • size: 128 kB
  • ctags: 15
  • sloc: perl: 194; makefile: 2
file content (301 lines) | stat: -rw-r--r-- 9,984 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
NAME
    "ExtUtils::CChecker" - configure-time utilities for using C headers,
    libraries, or OS features

SYNOPSIS
     use Module::Build;
     use ExtUtils::CChecker;

     my $check_PF_MOONLASER = <<'EOF';
     #include <stdio.h>
     #include <sys/socket.h>
     int main(int argc, char *argv[]) {
       printf("PF_MOONLASER is %d\n", PF_MOONLASER);
       return 0;
     }
     EOF

     ExtUtils::CChecker->new->assert_compile_run(
        diag => "no PF_MOONLASER",
        source => $check_PF_MOONLASER,
     );

     Module::Build->new(
       ...
     )->create_build_script;

DESCRIPTION
    Often Perl modules are written to wrap functionallity found in existing
    C headers, libraries, or to use OS-specific features. It is useful in
    the Build.PL or Makefile.PL file to check for the existance of these
    requirements before attempting to actually build the module.

    Objects in this class provide an extension around ExtUtils::CBuilder to
    simplify the creation of a .c file, compiling, linking and running it,
    to test if a certain feature is present.

    It may also be necessary to search for the correct library to link
    against, or for the right include directories to find header files in.
    This class also provides assistance here.

CONSTRUCTOR
  $cc = ExtUtils::CChecker->new
    Returns a new instance of a "ExtUtils::CChecker" object.

METHODS
  $dirs = $cc->include_dirs
    Returns the currently-configured include directories in an ARRAY
    reference.

  $flags = $cc->extra_compiler_flags
    Returns the currently-configured extra compiler flags in an ARRAY
    reference.

  $flags = $cc->extra_linker_flags
    Returns the currently-configured extra linker flags in an ARRAY
    reference.

  $success = $cc->try_compile_run( %args )
  $success = $cc->try_compile_run( $source )
    Try to compile, link, and execute a C program whose source is given.
    Returns true if the program compiled and linked, and exited
    successfully. Returns false if any of these steps fail.

    Takes the following named arguments. If a single argument is given, that
    is taken as the source string.

    *       source => STRING

            The source code of the C program to try compiling, building, and
            running.

    *       extra_compiler_flags => ARRAY

            Optional. If specified, pass extra flags to the compiler.

    *       extra_linker_flags => ARRAY

            Optional. If specified, pass extra flags to the linker.

    *       define => STRING

            Optional. If specified, then the named symbol will be defined on
            the C compiler commandline if the program ran successfully (by
            passing an option "-D*SYMBOL*").

  $cc->assert_compile_run( %args )
    Calls "try_compile_run". If it fails, die with an "OS unsupported"
    message. Useful to call from Build.PL or Makefile.PL.

    Takes one extra optional argument:

    *       diag => STRING

            If present, this string will be appended to the failure message
            if one is generated. It may provide more useful information to
            the user on why the OS is unsupported.

  $success = $cc->try_find_include_dirs_for( %args )
    Try to compile, link and execute the given source, using extra include
    directories.

    When a usable combination is found, the directories required are stored
    in the object for use in further compile operations, or returned by
    "include_dirs". The method then returns true.

    If no a usable combination is found, it returns false.

    Takes the following arguments:

    *       source => STRING

            Source code to compile

    *       dirs => ARRAY of ARRAYs

            Gives a list of sets of dirs. Each set of dirs should be strings
            in its own array reference.

    *       define => STRING

            Optional. If specified, then the named symbol will be defined on
            the C compiler commandline if the program ran successfully (by
            passing an option "-D*SYMBOL*").

  $success = $cc->try_find_libs_for( %args )
    Try to compile, link and execute the given source, when linked against a
    given set of extra libraries.

    When a usable combination is found, the libraries required are stored in
    the object for use in further link operations, or returned by
    "extra_linker_flags". The method then returns true.

    If no usable combination is found, it returns false.

    Takes the following arguments:

    *       source => STRING

            Source code to compile

    *       libs => ARRAY of STRINGs

            Gives a list of sets of libraries. Each set of libraries should
            be space-separated.

    *       define => STRING

            Optional. If specified, then the named symbol will be defined on
            the C compiler commandline if the program ran successfully (by
            passing an option "-D*SYMBOL*").

  $cc->find_include_dirs_for( %args )
  $cc->find_libs_for( %args )
    Calls "try_find_include_dirs_for" or "try_find_libs_for" respectively.
    If it fails, die with an "OS unsupported" message.

    Each method takes one extra optional argument:

    *       diag => STRING

            If present, this string will be appended to the failure message
            if one is generated. It may provide more useful information to
            the user on why the OS is unsupported.

  $mb = $cc->new_module_build( %args )
    Construct and return a new Module::Build object, preconfigured with the
    "include_dirs", "extra_compiler_flags" and "extra_linker_flags" options
    that have been configured on this object, by the above methods.

    This is provided as a simple shortcut for the common use case, that a
    Build.PL file is using the "ExtUtils::CChecker" object to detect the
    required arguments to pass.

EXAMPLES
  Socket Libraries
    Some operating systems provide the BSD sockets API in their primary
    libc. Others keep it in a separate library which should be linked
    against. The following example demonstrates how this would be handled.

     use Module::Build;
     use ExtUtils::CChecker;

     my $cc = ExtUtils::CChecker->new;

     $cc->find_libs_for(
        diag => "no socket()",
        libs => [ "", "socket nsl" ],
        source => q[
     #include <sys/socket.h>
     int main(int argc, char *argv) {
       int fd = socket(PF_INET, SOCK_STREAM, 0);
       if(fd < 0)
         return 1;
       return 0;
     }
     ] );

     $cc->new_module_build(
        module_name => "Your::Name::Here",
        requires => {
           'IO::Socket' => 0,
        },
        ...
     )->create_build_script;

    By using the "new_module_build" method, the detected
    "extra_linker_flags" value has been automatically passed into the new
    "Module::Build" object.

  Testing For Optional Features
    Sometimes a function or ability may be optionally provided by the OS, or
    you may wish your module to be useable when only partial support is
    provided, without requiring it all to be present. In these cases it is
    traditional to detect the presence of this optional feature in the
    Build.PL script, and define a symbol to declare this fact if it is
    found. The XS code can then use this symbol to select between differing
    implementations. For example, the Build.PL:

     use Module::Build;
     use ExtUtils::CChecker;

     my $cc = ExtUtils::CChecker->new;

     $cc->try_compile_run(
        define => "HAVE_MANGO",
        source => <<'EOF' );
     #include <mango.h>
     #include <unistd.h>
     int main(void) {
       if(mango() != 0)
         exit(1);
       exit(0);
     }
     EOF

     $cc->new_module_build(
        ...
     )->create_build_script;

    If the C code compiles and runs successfully, and exits with a true
    status, the symbol "HAVE_MANGO" will be defined on the compiler
    commandline. This allows the XS code to detect it, for example

     int
     mango()
       CODE:
     #ifdef HAVE_MANGO
         RETVAL = mango();
     #else
         croak("mango() not implemented");
     #endif
       OUTPUT:
         RETVAL

    This module will then still compile even if the operating system lacks
    this particular function. Trying to invoke the function at runtime will
    simply throw an exception.

  Linux Kernel Headers
    Operating systems built on top of the Linux kernel often share a looser
    association with their kernel version than most other operating systems.
    It may be the case that the running kernel is newer, containing more
    features, than the distribution's libc headers would believe. In such
    circumstances it can be difficult to make use of new socket options,
    "ioctl()"s, etc.. without having the constants that define them and
    their parameter structures, because the relevant header files are not
    visible to the compiler. In this case, there may be little choice but to
    pull in some of the kernel header files, which will provide the required
    constants and structures.

    The Linux kernel headers can be found using the /lib/modules directory.
    A fragment in Build.PL like the following, may be appropriate.

     chomp( my $uname_r = `uname -r` );

     my @dirs = (
        [],
        [ "/lib/modules/$uname_r/source/include" ],
     );

     $cc->find_include_dirs_for(
        diag => "no PF_MOONLASER",
        dirs => \@dirs,
        source => <<'EOF' );
     #include <sys/socket.h>
     #include <moon/laser.h>
     int family = PF_MOONLASER;
     struct laserwl lwl;
     int main(int argc, char *argv[]) {
       return 0;
     }
     EOF

    This fragment will first try to compile the program as it stands, hoping
    that the libc headers will be sufficient. If it fails, it will then try
    including the kernel headers, which should make the constant and
    structure visible, allowing the program to compile.

AUTHOR
    Paul Evans <leonerd@leonerd.org.uk>