1=head1 NAME
2
3InlineX Cookbook
4
5=head1 BASIC EXAMPLE
6
7As of version 0.13 of this module, it's possible to provide the C/CPP
8code to InlineX::C2XS/InlineX::CPP2XS by supplying either the CODE or
9SRC_LOCATION arguments as key/value pairs in the hashref that forms the
10the final argument given to c2xs()/cpp2xs(). This documentation was
11first written prior to version 0.13 - I'll leave the first parts of it
12as is, but bear in mind that the C source can now be stored anywhere in
13any file and you just provide the name and location (either fully
14qualified or relative) of that file using the
15SRC_LOCATION=>'./location/file.ext' key/value pair ... or you can just
16store the code as one big string in a variable (say, $code) in which
17case you supply the code using the CODE=>$code key/value pair. For a
18demo of these capabilities that became available in 0.13, see the
19section "UPDATE for 0.13 and later" at the end of this document.
20
21The examples that follow here utilise InlineX::C2XS. The same
22principles apply to InlineX::CPP2XS.
23
24Create a separate directory to work through this demo (let's call it
25'test' - though you can call it whatever you like), then 'cd' to the
26newly created 'test' directory, and create 2 folders in it - 'src' and
27'My-Mod-0.01'. The 'src' folder is where the C code gets placed (and
28the folder must be named 'src'). The 'My-Mod-0.01' folder is where the
29various files that InlineX can create will be written. (That folder does
30not have to be named 'My-Mod-0.01' - call it whatever you want. For the
31purpose of this exercise, I'm assuming you *have* named it'My-Mod-0.01').
32
33In the 'src' folder place a C file named Mod.c that contains:
34
35
36    int plus (int x, int y) {
37        return x + y;
38    }
39    int minus (int x, int y) {
40        return x - y;
41    }
42
43
44Since the module we are building in this particular exercise is named
45My::Mod, the C file must be named 'Mod.c'. That is, the .c file must
46have a '.c' extension, and it must have the same name as the .pm file.
47
48To create Mod.xs, place the following file (which I've named 'create.pl')
49in the 'test' directory:
50
51
52    use warnings;
53    use strict;
54    use InlineX::C2XS qw(c2xs);
55    my $mod = 'My::Mod';
56    my $pkg = $mod;
57    my $build_dir = './My-Mod-0.01';
58    c2xs($mod, $pkg, $build_dir);
59
60
61Then run create.pl.
62
63You should now find Mod.xs in test/My-Mod-0.01. We've taken care of
64one of the files that we'll need to build My::Mod. Note that INLINE.h
65was not created. That's because the C code in Mod.c does not need
66INLINE.h. Let's change that by adding the following to the bottom of
67Mod.c:
68
69
70    void plus_minus(int x, int y) {
71         Inline_Stack_Vars;
72         Inline_Stack_Reset;
73         Inline_Stack_Push(sv_2mortal(newSViv(x + y)));
74         Inline_Stack_Push(sv_2mortal(newSViv(x - y)));
75         Inline_Stack_Done;
76         Inline_Stack_Return(2);
77    }
78
79
80Again run create.pl
81
82This time INLINE.h is needed and you should find it, along with Mod.xs,
83in test/My-Mod-0.01.
84
85But, of course, to build the My::Mod module, you'll also need a
86Makefile.PL and a Mod.pm. So let's autogenerate them, too. It's just
87a matter of providing an extra argument to c2xs(). Amend create.pl to:
88
89
90    use warnings;
91    use strict;
92    use InlineX::C2XS qw(c2xs);
93    my $mod = 'My::Mod';
94    my $pkg = $mod;
95    my $build_dir = './My-Mod-0.01';
96    my $hashref = {VERSION =>0.01,
97                   WRITE_MAKEFILE_PL => 1,
98                   WRITE_PM => 1};
99    c2xs($mod, $pkg, $build_dir, $hashref);
100
101
102Now when you run create.pl you'll find that Makefile.PL and Mod.pm
103are also created in test/My-Mod-0.01.(Mod.pm doesn't contain any pod
104documentation - and the Makefile.PL might contain some
105machine-specific specifications that should be cleaned up before
106sending the files off to CPAN. But that's all fairly basic and
107straightforward stuff.)
108If you want all of the XSubs except those starting with a single
109underscore (but not multiple underscores) to be placed into Mod.pm's
110@EXPORT then set EXPORT_ALL=>1 in $hashref. Otherwise
111@My::Mod::EXPORT will be empty.
112If you want all of the XSubs except those starting with a single
113underscore (but not multiple underscores) to be placed into Mod.pm's
114@EXPORT_OK then set EXPORT_OK_ALL=>1 in $hashref. Otherwise
115@My::Mod::EXPORT_OK will be empty.
116And if you want to create an export tag (named, eg 'all') that includes
117all of the XSubs except those starting with a single underscore (but
118not multiple underscores) then set EXPORT_TAGS_ALL=>'all' in
119$hashref.
120
121You may also want to provide a test script, a README, a MANIFEST and
122whatever other files you like. These additional files cannot be
123autogenerated by InlineX. For a test script that works with the
124autogenerated Mod.pm, just create a file named 'test.t' in
125test/My-Mod-0.01/t (you'll need to manually create that 't'
126directory). Assuming that we haven't set either EXPORT_OK_ALL or
127EXPORT_ALL (see above), 'test.t' could look like this:
128
129    use warnings;
130    use strict;
131    use My::Mod;
132    print "1..1\n";
133    my $x = 16;
134    my $y = 12;
135    my @z = My::Mod::plus_minus($x, $y);
136    my $ok = '';
137    if(My::Mod::plus($x, $y) == 28) {$ok .= 'a'}
138    if(My::Mod::minus($x, $y) == 4) {$ok .= 'b'}
139    if($z[0] == 28 && $z[1] == 4)   {$ok .= 'c'}
140    if($ok eq 'abc') {print "ok 1\n"}
141    else {print "not ok 1 $ok\n"}
142
143If we have set EXPORT_OK_ALL, then 'test.t' could look like this:
144
145    use warnings;
146    use strict;
147    use My::Mod qw(plus minus plus_minus);
148    print "1..1\n";
149    my $x = 16;
150    my $y = 12;
151    my @z = plus_minus($x, $y);
152    my $ok = '';
153    if(plus($x, $y) == 28) {$ok .= 'a'}
154    if(minus($x, $y) == 4) {$ok .= 'b'}
155    if($z[0] == 28 && $z[1] == 4)   {$ok .= 'c'}
156    if($ok eq 'abc') {print "ok 1\n"}
157    else {print "not ok 1 $ok\n"}
158
159And if we have instead set EXPORT_ALL, then in 'test.t' we
160could replace "use My::Mod qw(plus minus plus_minus);" with
161simply "use My::Mod;"
162
163Now you can build My::Mod in the usual way (in the
164test/My-Mod-0.01 folder) by running:
165
166    perl Makefile.PL
167    make test
168
169You could even install it by running 'make install' if you want.
170
171There are other examples to be found in the demos folder of the
172InlineX-C2XS and InlineX-CPP2XS source distributions from CPAN.
173
174Some other build options are given below. (For a complete list, see
175the InlineX-C2XS/InlineX-CPP2xs documentation.) In each case it's just
176a matter of adding a key/value pair to $hashref in create.pl. No other
177changes to create.pl are necessary.
178
179**********************************************************************
180
181=head1 AUTO_INCLUDE
182
183You may need to include additional headers into the XS file. Do so by
184inserting the following key/value assignment into create.pl's $hashref:
185
186    AUTO_INCLUDE => "#include <x.h>\n#include \"y.h\"",
187
188Also, if the AUTOWRAP feature needs to parse and use these headers,
189then AUTO_INCLUDE is the way to satisfy that requirement.
190
191**********************************************************************
192
193=head1 BUILD_NOISY
194
195You'll note that during the running of create.pl there's some progress
196reports being generated by Inline::C. If you don't want to see those
197reports, insert the following key/value assignment into create.pl's
198$hashfef:
199
200    BUILD_NOISY => 0,
201
202**********************************************************************
203
204=head1 USING
205
206By default Parse::RecDescent is used to parse the C code. Inline comes
207with another C parser called 'ParseRegExp'. It's much faster than
208Parse::RecDescent. To use Parse::RegExp:
209
210   USING => ['ParseRegExp'],
211
212**********************************************************************
213
214=head1 TYPEMAPS
215
216Let's do another demo here, based upon the "Object Oriented Inline"
217example in the (excellent) Inline::C-Cookbook - to demonstrate the
218use of typemaps as much as anything else. Back in the 'test' folder,
219create another folder named '/My-Soldier-1.02' ... so we've now got
220folders named test/src, test/My-Mod-0.01 and test/My-Soldier-1.02.
221
222Create a file named 'Soldier.c' as follows (and place it in test/src):
223
224  typedef struct {
225    char* name;
226    char* rank;
227    long  serial;
228  } Soldier;
229
230  Soldier * new(char* class, char* name, char* rank, long serial) {
231      Soldier* soldier;
232      New(42, soldier, 1, Soldier);
233
234      soldier->name = savepv(name);
235      soldier->rank = savepv(rank);
236      soldier->serial = serial;
237
238      return soldier;
239  }
240
241  char* get_name(Soldier * obj) {
242        return obj->name;
243  }
244
245  char* get_rank(Soldier * obj) {
246        return obj->rank;
247  }
248
249  long get_serial(Soldier * obj) {
250       return obj->serial;
251  }
252
253  void DESTROY(Soldier* obj) {
254       Safefree(obj->name);
255       Safefree(obj->rank);
256       Safefree(obj);
257  }
258
259
260Note that new() returns a Soldier*. Perl doesn't know anything about
261the Soldier* type ... so we need to provide a typemap with an 'OUTPUT'
262section that tells perl how to deal with this type.
263Note also that the other functions take (as their argument) a Soldier*.
264Again, since perl doesn't know anything about the Soldier* type, we
265need to provide a typemap with an 'INPUT' section that tells perl
266what to do. Here's one such typemap that satisfies both requirements:
267
268
269 Soldier *    SOLDIER
270
271 INPUT
272 SOLDIER
273 	$var = INT2PTR($type, SvIV(SvRV($arg)))
274
275 OUTPUT
276 SOLDIER
277 	$arg     = newSViv(0);
278	sv_setiv(newSVrv($arg, \"Soldier\"), (IV)$var);
279	SvREADONLY_on(SvRV($arg));
280	$arg;
281
282
283Save that file as test/My-Soldier-1.02/typemap and place a copy of it
284in 'test'. Note that, in addition to our typemap being needed when we
285compile the My::Soldier module, the c2xs() function also needs it in
286order to write a correct XS file. That's why we've placed a copy of
287the typemap in both 'test' and 'test/My-Soldier-1.02' - so that both
288processes will be able to find it. A better solution is to have the
289TYPEMAPS entry in $hashref provide a fully qualified (absolute) path
290to the file, rather than a relative path. (Unfortunately, I don't
291know what that absolute path will be on your machine.)
292
293I guess we'll also need a test file to test our new Soldier module.
294So save the following as test/My-Soldier-1.02/t/test.t:
295
296    use warnings;
297    use strict;
298    use My::Soldier;
299    print "1..1'\n";
300    my $obj1 = My::Soldier->new('Benjamin', 'Private', 11111);
301    my $obj2 = My::Soldier->new('Sanders', 'Colonel', 22222);
302    my $obj3 = My::Soldier->new('Matt', 'Sergeant', 33333);
303    my $ok = '';
304    if($obj1->My::Soldier::get_name() eq 'Benjamin') {$ok .= 'a'}
305    if($obj2->My::Soldier::get_name() eq 'Sanders') {$ok .= 'b'}
306    if($obj3->My::Soldier::get_name() eq 'Matt') {$ok .= 'c'}
307    if($obj1->My::Soldier::get_rank() eq 'Private') {$ok .= 'd'}
308    if($obj2->My::Soldier::get_rank() eq 'Colonel') {$ok .= 'e'}
309    if($obj3->My::Soldier::get_rank() eq 'Sergeant') {$ok .= 'f'}
310    if($obj1->My::Soldier::get_serial() == 11111) {$ok .= 'g'}
311    if($obj2->My::Soldier::get_serial() == 22222) {$ok .= 'h'}
312    if($obj3->My::Soldier::get_serial() == 33333) {$ok .= 'i'}
313    if($ok eq 'abcdefghi') {print "ok 1\n"}
314    else {print "not ok 1 $ok\n"}
315
316Now we just need to rewrite test/create.pl appropriately:
317
318    use warnings;
319    use strict;
320    use InlineX::C2XS qw(c2xs);
321    my $mod = 'My::Soldier';
322    my $pkg = $mod;
323    my $build_dir = './My-Soldier-1.02';
324    my $hashref = {VERSION =>1.02,
325                   WRITE_MAKEFILE_PL => 1,
326                   TYPEMAPS => ['./typemap'],
327                   WRITE_PM => 1};
328    c2xs($mod, $pkg, $build_dir, $hashref);
329
330So now ... it's just a matter of running create.pl - then 'cd' to
331test/My-Soldier-1.02 and run:
332
333  perl Makefile.PL
334  make test
335
336(and 'make install' if you actually want to install this module.)
337
338**********************************************************************
339
340=head1 UPDATE for 0.13 and later
341
342Returning to the first example code we used at the beginning of this
343cookbook, with version 0.13 or later, we don't need to have the source
344in ./src/Mod.c. (We can still do it that way, but we don't *have* to.)
345
346We could, for example, put the code that was written into './src/Mod.c'
347into '/home/me/file.ext' instead. Then, in order to create Mod.xs,
348Mod.pm, and Makefile.PL in './My-Mod-0.01', we need 'create.pl' to
349look like this:
350
351
352    use warnings;
353    use strict;
354    use InlineX::C2XS qw(c2xs);
355    my $mod = 'My::Mod';
356    my $pkg = $mod;
357    my $build_dir = './My-Mod-0.01';
358    my $hashref = {VERSION =>0.01,
359                   WRITE_MAKEFILE_PL => 1,
360                   WRITE_PM => 1,
361                   SRC_LOCATION => '/home/me/file.ext'};
362    c2xs($mod, $pkg, $build_dir, $hashref);
363
364
365Another alternative is to put the code in a variable - in which
366case 'create.pl' is as follows:
367
368
369    use warnings;
370    use strict;
371    use InlineX::C2XS qw(c2xs);
372    my $mod = 'My::Mod';
373    my $pkg = $mod;
374    my $build_dir = './My-Mod-0.01';
375    my $code = "
376    int plus (int x, int y) {
377        return x + y;
378    }
379    int minus (int x, int y) {
380        return x - y;
381    }
382
383    void plus_minus(int x, int y) {
384         Inline_Stack_Vars;
385         Inline_Stack_Reset;
386         Inline_Stack_Push(sv_2mortal(newSViv(x + y)));
387         Inline_Stack_Push(sv_2mortal(newSViv(x - y)));
388         Inline_Stack_Done;
389         Inline_Stack_Return(2);
390    }
391    ";
392    my $hashref = {VERSION =>0.01,
393                   WRITE_MAKEFILE_PL => 1,
394                   WRITE_PM => 1,
395                   CODE => $code};
396    c2xs($mod, $pkg, $build_dir, $hashref);
397
398
399**********************************************************************
400
401=cut
402
403
404
405