Commit | Line | Data |
4633a7c4 |
1 | =head1 NAME |
2 | |
360e660c |
3 | perlXStut - Tutorial for writing XSUBs |
4633a7c4 |
4 | |
5 | =head1 DESCRIPTION |
6 | |
7 | This tutorial will educate the reader on the steps involved in creating |
c07a80fd |
8 | a Perl extension. The reader is assumed to have access to L<perlguts> and |
4633a7c4 |
9 | L<perlxs>. |
10 | |
11 | This tutorial starts with very simple examples and becomes more complex, |
c07a80fd |
12 | with each new example adding new features. Certain concepts may not be |
360e660c |
13 | completely explained until later in the tutorial in order to slowly ease |
14 | the reader into building extensions. |
4633a7c4 |
15 | |
360e660c |
16 | This tutorial was written from a Unix point of view. Where I know them |
17 | to be otherwise different for other platforms (e.g. Win32), I will list |
18 | them. If you find something that was missed, please let me know. |
4633a7c4 |
19 | |
360e660c |
20 | =head1 SPECIAL NOTES |
c07a80fd |
21 | |
360e660c |
22 | =head2 make |
c07a80fd |
23 | |
360e660c |
24 | This tutorial assumes that the make program that Perl is configured to |
25 | use is called C<make>. Instead of running "make" in the examples that |
26 | follow, you may have to substitute whatever make program Perl has been |
27 | configured to use. Running "perl -V:make" should tell you what it is. |
c07a80fd |
28 | |
360e660c |
29 | =head2 Version caveat |
c07a80fd |
30 | |
360e660c |
31 | This tutorial tries hard to keep up with the latest development versions |
32 | of Perl. This often means that it is sometimes in advance of the latest |
33 | released version of Perl, and that certain features described here might |
34 | not work on earlier versions. See the section on "Troubleshooting |
35 | these Examples" for more information. |
c07a80fd |
36 | |
360e660c |
37 | =head2 Dynamic Loading versus Static Loading |
c07a80fd |
38 | |
39 | It is commonly thought that if a system does not have the capability to |
360e660c |
40 | dynamically load a library, you cannot build XSUBs. This is incorrect. |
41 | You I<can> build them, but you must link the XSUBs subroutines with the |
c07a80fd |
42 | rest of Perl, creating a new executable. This situation is similar to |
43 | Perl 4. |
44 | |
45 | This tutorial can still be used on such a system. The XSUB build mechanism |
46 | will check the system and build a dynamically-loadable library if possible, |
47 | or else a static library and then, optionally, a new statically-linked |
48 | executable with that static library linked in. |
49 | |
50 | Should you wish to build a statically-linked executable on a system which |
51 | can dynamically load libraries, you may, in all the following examples, |
360e660c |
52 | where the command "C<make>" with no arguments is executed, run the command |
53 | "C<make perl>" instead. |
c07a80fd |
54 | |
55 | If you have generated such a statically-linked executable by choice, then |
360e660c |
56 | instead of saying "C<make test>", you should say "C<make test_static>". |
57 | On systems that cannot build dynamically-loadable libraries at all, simply |
58 | saying "C<make test>" is sufficient. |
59 | |
60 | =head1 TUTORIAL |
61 | |
62 | Now let's go on with the show! |
c07a80fd |
63 | |
64 | =head2 EXAMPLE 1 |
4633a7c4 |
65 | |
66 | Our first extension will be very simple. When we call the routine in the |
c07a80fd |
67 | extension, it will print out a well-known message and return. |
4633a7c4 |
68 | |
360e660c |
69 | Run "C<h2xs -A -n Mytest>". This creates a directory named Mytest, |
70 | possibly under ext/ if that directory exists in the current working |
71 | directory. Several files will be created in the Mytest dir, including |
72 | MANIFEST, Makefile.PL, Mytest.pm, Mytest.xs, test.pl, and Changes. |
4633a7c4 |
73 | |
360e660c |
74 | The MANIFEST file contains the names of all the files just created in the |
75 | Mytest directory. |
4633a7c4 |
76 | |
77 | The file Makefile.PL should look something like this: |
78 | |
79 | use ExtUtils::MakeMaker; |
80 | # See lib/ExtUtils/MakeMaker.pm for details of how to influence |
81 | # the contents of the Makefile that is written. |
82 | WriteMakefile( |
360e660c |
83 | NAME => 'Mytest', |
84 | VERSION_FROM => 'Mytest.pm', # finds $VERSION |
85 | LIBS => [''], # e.g., '-lm' |
86 | DEFINE => '', # e.g., '-DHAVE_SOMETHING' |
87 | INC => '', # e.g., '-I/usr/include/other' |
4633a7c4 |
88 | ); |
89 | |
791fa977 |
90 | The file Mytest.pm should start with something like this: |
c07a80fd |
91 | |
791fa977 |
92 | package Mytest; |
4633a7c4 |
93 | |
360e660c |
94 | use strict; |
360e660c |
95 | |
4633a7c4 |
96 | require Exporter; |
97 | require DynaLoader; |
c07a80fd |
98 | |
77ca0c92 |
99 | our @ISA = qw(Exporter DynaLoader); |
4633a7c4 |
100 | # Items to export into callers namespace by default. Note: do not export |
101 | # names by default without a very good reason. Use EXPORT_OK instead. |
102 | # Do not simply export all your public functions/methods/constants. |
77ca0c92 |
103 | our @EXPORT = qw( |
c07a80fd |
104 | |
4633a7c4 |
105 | ); |
77ca0c92 |
106 | our $VERSION = '0.01'; |
c07a80fd |
107 | |
791fa977 |
108 | bootstrap Mytest $VERSION; |
c07a80fd |
109 | |
4633a7c4 |
110 | # Preloaded methods go here. |
c07a80fd |
111 | |
4633a7c4 |
112 | # Autoload methods go after __END__, and are processed by the autosplit program. |
c07a80fd |
113 | |
4633a7c4 |
114 | 1; |
115 | __END__ |
c07a80fd |
116 | # Below is the stub of documentation for your module. You better edit it! |
4633a7c4 |
117 | |
360e660c |
118 | The rest of the .pm file contains sample code for providing documentation for |
119 | the extension. |
120 | |
121 | Finally, the Mytest.xs file should look something like this: |
4633a7c4 |
122 | |
123 | #include "EXTERN.h" |
124 | #include "perl.h" |
125 | #include "XSUB.h" |
791fa977 |
126 | |
127 | MODULE = Mytest PACKAGE = Mytest |
4633a7c4 |
128 | |
129 | Let's edit the .xs file by adding this to the end of the file: |
130 | |
131 | void |
132 | hello() |
360e660c |
133 | CODE: |
4633a7c4 |
134 | printf("Hello, world!\n"); |
135 | |
360e660c |
136 | It is okay for the lines starting at the "CODE:" line to not be indented. |
137 | However, for readability purposes, it is suggested that you indent CODE: |
138 | one level and the lines following one more level. |
139 | |
140 | Now we'll run "C<perl Makefile.PL>". This will create a real Makefile, |
d9d2a7fb |
141 | which make needs. Its output looks something like: |
4633a7c4 |
142 | |
143 | % perl Makefile.PL |
144 | Checking if your kit is complete... |
145 | Looks good |
791fa977 |
146 | Writing Makefile for Mytest |
4633a7c4 |
147 | % |
148 | |
360e660c |
149 | Now, running make will produce output that looks something like this (some |
150 | long lines have been shortened for clarity and some extraneous lines have |
151 | been deleted): |
4633a7c4 |
152 | |
153 | % make |
791fa977 |
154 | umask 0 && cp Mytest.pm ./blib/Mytest.pm |
155 | perl xsubpp -typemap typemap Mytest.xs >Mytest.tc && mv Mytest.tc Mytest.c |
360e660c |
156 | Please specify prototyping behavior for Mytest.xs (see perlxs manual) |
791fa977 |
157 | cc -c Mytest.c |
158 | Running Mkbootstrap for Mytest () |
159 | chmod 644 Mytest.bs |
160 | LD_RUN_PATH="" ld -o ./blib/PA-RISC1.1/auto/Mytest/Mytest.sl -b Mytest.o |
161 | chmod 755 ./blib/PA-RISC1.1/auto/Mytest/Mytest.sl |
162 | cp Mytest.bs ./blib/PA-RISC1.1/auto/Mytest/Mytest.bs |
163 | chmod 644 ./blib/PA-RISC1.1/auto/Mytest/Mytest.bs |
360e660c |
164 | Manifying ./blib/man3/Mytest.3 |
165 | % |
166 | |
167 | You can safely ignore the line about "prototyping behavior". |
168 | |
169 | If you are on a Win32 system, and the build process fails with linker |
170 | errors for functions in the C library, check if your Perl is configured |
171 | to use PerlCRT (running "perl -V:libc" should show you if this is the |
172 | case). If Perl is configured to use PerlCRT, you have to make sure |
173 | PerlCRT.lib is copied to the same location that msvcrt.lib lives in, |
174 | so that the compiler can find it on its own. msvcrt.lib is usually |
175 | found in the Visual C compiler's lib directory (e.g. C:/DevStudio/VC/lib). |
c07a80fd |
176 | |
360e660c |
177 | Perl has its own special way of easily writing test scripts, but for this |
178 | example only, we'll create our own test script. Create a file called hello |
c07a80fd |
179 | that looks like this: |
180 | |
c07a80fd |
181 | #! /opt/perl5/bin/perl |
360e660c |
182 | |
d9d2a7fb |
183 | use ExtUtils::testlib; |
360e660c |
184 | |
791fa977 |
185 | use Mytest; |
360e660c |
186 | |
791fa977 |
187 | Mytest::hello(); |
4633a7c4 |
188 | |
360e660c |
189 | Now we make the script executable (C<chmod -x hello>), run the script |
190 | and we should see the following output: |
4633a7c4 |
191 | |
360e660c |
192 | % ./hello |
4633a7c4 |
193 | Hello, world! |
194 | % |
195 | |
c07a80fd |
196 | =head2 EXAMPLE 2 |
4633a7c4 |
197 | |
360e660c |
198 | Now let's add to our extension a subroutine that will take a single numeric |
199 | argument as input and return 0 if the number is even or 1 if the number |
200 | is odd. |
4633a7c4 |
201 | |
791fa977 |
202 | Add the following to the end of Mytest.xs: |
4633a7c4 |
203 | |
204 | int |
205 | is_even(input) |
206 | int input |
360e660c |
207 | CODE: |
c07a80fd |
208 | RETVAL = (input % 2 == 0); |
360e660c |
209 | OUTPUT: |
4633a7c4 |
210 | RETVAL |
211 | |
360e660c |
212 | There does not need to be white space at the start of the "C<int input>" |
213 | line, but it is useful for improving readability. Placing a semi-colon at |
214 | the end of that line is also optional. Any amount and kind of white space |
215 | may be placed between the "C<int>" and "C<input>". |
4633a7c4 |
216 | |
360e660c |
217 | Now re-run make to rebuild our new shared library. |
4633a7c4 |
218 | |
c07a80fd |
219 | Now perform the same steps as before, generating a Makefile from the |
220 | Makefile.PL file, and running make. |
4633a7c4 |
221 | |
360e660c |
222 | In order to test that our extension works, we now need to look at the |
c07a80fd |
223 | file test.pl. This file is set up to imitate the same kind of testing |
224 | structure that Perl itself has. Within the test script, you perform a |
225 | number of tests to confirm the behavior of the extension, printing "ok" |
d9d2a7fb |
226 | when the test is correct, "not ok" when it is not. Change the print |
227 | statement in the BEGIN block to print "1..4", and add the following code |
228 | to the end of the file: |
c07a80fd |
229 | |
791fa977 |
230 | print &Mytest::is_even(0) == 1 ? "ok 2" : "not ok 2", "\n"; |
231 | print &Mytest::is_even(1) == 0 ? "ok 3" : "not ok 3", "\n"; |
232 | print &Mytest::is_even(2) == 1 ? "ok 4" : "not ok 4", "\n"; |
c07a80fd |
233 | |
360e660c |
234 | We will be calling the test script through the command "C<make test>". You |
c07a80fd |
235 | should see output that looks something like this: |
236 | |
237 | % make test |
360e660c |
238 | PERL_DL_NONLAZY=1 /opt/perl5.004/bin/perl (lots of -I arguments) test.pl |
c07a80fd |
239 | 1..4 |
240 | ok 1 |
241 | ok 2 |
242 | ok 3 |
243 | ok 4 |
4633a7c4 |
244 | % |
245 | |
360e660c |
246 | =head2 What has gone on? |
4633a7c4 |
247 | |
248 | The program h2xs is the starting point for creating extensions. In later |
c07a80fd |
249 | examples we'll see how we can use h2xs to read header files and generate |
4633a7c4 |
250 | templates to connect to C routines. |
251 | |
252 | h2xs creates a number of files in the extension directory. The file |
253 | Makefile.PL is a perl script which will generate a true Makefile to build |
254 | the extension. We'll take a closer look at it later. |
255 | |
360e660c |
256 | The .pm and .xs files contain the meat of the extension. The .xs file holds |
257 | the C routines that make up the extension. The .pm file contains routines |
258 | that tell Perl how to load your extension. |
259 | |
260 | Generating the Makefile and running C<make> created a directory called blib |
261 | (which stands for "build library") in the current working directory. This |
262 | directory will contain the shared library that we will build. Once we have |
263 | tested it, we can install it into its final location. |
264 | |
265 | Invoking the test script via "C<make test>" did something very important. |
266 | It invoked perl with all those C<-I> arguments so that it could find the |
267 | various files that are part of the extension. It is I<very> important that |
268 | while you are still testing extensions that you use "C<make test>". If you |
269 | try to run the test script all by itself, you will get a fatal error. |
270 | Another reason it is important to use "C<make test>" to run your test |
271 | script is that if you are testing an upgrade to an already-existing version, |
272 | using "C<make test>" insures that you will test your new extension, not the |
273 | already-existing version. |
4633a7c4 |
274 | |
c07a80fd |
275 | When Perl sees a C<use extension;>, it searches for a file with the same name |
360e660c |
276 | as the C<use>'d extension that has a .pm suffix. If that file cannot be found, |
c07a80fd |
277 | Perl dies with a fatal error. The default search path is contained in the |
360e660c |
278 | C<@INC> array. |
4633a7c4 |
279 | |
791fa977 |
280 | In our case, Mytest.pm tells perl that it will need the Exporter and Dynamic |
360e660c |
281 | Loader extensions. It then sets the C<@ISA> and C<@EXPORT> arrays and the |
282 | C<$VERSION> scalar; finally it tells perl to bootstrap the module. Perl |
283 | will call its dynamic loader routine (if there is one) and load the shared |
284 | library. |
4633a7c4 |
285 | |
360e660c |
286 | The two arrays C<@ISA> and C<@EXPORT> are very important. The C<@ISA> |
c07a80fd |
287 | array contains a list of other packages in which to search for methods (or |
360e660c |
288 | subroutines) that do not exist in the current package. This is usually |
289 | only important for object-oriented extensions (which we will talk about |
290 | much later), and so usually doesn't need to be modified. |
4633a7c4 |
291 | |
360e660c |
292 | The C<@EXPORT> array tells Perl which of the extension's variables and |
293 | subroutines should be placed into the calling package's namespace. Because |
294 | you don't know if the user has already used your variable and subroutine |
295 | names, it's vitally important to carefully select what to export. Do I<not> |
296 | export method or variable names I<by default> without a good reason. |
4633a7c4 |
297 | |
c07a80fd |
298 | As a general rule, if the module is trying to be object-oriented then don't |
360e660c |
299 | export anything. If it's just a collection of functions and variables, then |
300 | you can export them via another array, called C<@EXPORT_OK>. This array |
301 | does not automatically place its subroutine and variable names into the |
302 | namespace unless the user specifically requests that this be done. |
4633a7c4 |
303 | |
c07a80fd |
304 | See L<perlmod> for more information. |
4633a7c4 |
305 | |
360e660c |
306 | The C<$VERSION> variable is used to ensure that the .pm file and the shared |
791fa977 |
307 | library are "in sync" with each other. Any time you make changes to |
308 | the .pm or .xs files, you should increment the value of this variable. |
309 | |
360e660c |
310 | =head2 Writing good test scripts |
791fa977 |
311 | |
312 | The importance of writing good test scripts cannot be overemphasized. You |
313 | should closely follow the "ok/not ok" style that Perl itself uses, so that |
314 | it is very easy and unambiguous to determine the outcome of each test case. |
315 | When you find and fix a bug, make sure you add a test case for it. |
316 | |
360e660c |
317 | By running "C<make test>", you ensure that your test.pl script runs and uses |
791fa977 |
318 | the correct version of your extension. If you have many test cases, you |
360e660c |
319 | might want to copy Perl's test style. Create a directory named "t" in the |
320 | extension's directory and append the suffix ".t" to the names of your test |
321 | files. When you run "C<make test>", all of these test files will be executed. |
4633a7c4 |
322 | |
c07a80fd |
323 | =head2 EXAMPLE 3 |
4633a7c4 |
324 | |
325 | Our third extension will take one argument as its input, round off that |
c07a80fd |
326 | value, and set the I<argument> to the rounded value. |
4633a7c4 |
327 | |
791fa977 |
328 | Add the following to the end of Mytest.xs: |
4633a7c4 |
329 | |
330 | void |
331 | round(arg) |
332 | double arg |
360e660c |
333 | CODE: |
4633a7c4 |
334 | if (arg > 0.0) { |
335 | arg = floor(arg + 0.5); |
336 | } else if (arg < 0.0) { |
337 | arg = ceil(arg - 0.5); |
338 | } else { |
339 | arg = 0.0; |
340 | } |
360e660c |
341 | OUTPUT: |
4633a7c4 |
342 | arg |
343 | |
c07a80fd |
344 | Edit the Makefile.PL file so that the corresponding line looks like this: |
4633a7c4 |
345 | |
346 | 'LIBS' => ['-lm'], # e.g., '-lm' |
347 | |
360e660c |
348 | Generate the Makefile and run make. Change the BEGIN block to print |
c07a80fd |
349 | "1..9" and add the following to test.pl: |
4633a7c4 |
350 | |
791fa977 |
351 | $i = -1.5; &Mytest::round($i); print $i == -2.0 ? "ok 5" : "not ok 5", "\n"; |
352 | $i = -1.1; &Mytest::round($i); print $i == -1.0 ? "ok 6" : "not ok 6", "\n"; |
353 | $i = 0.0; &Mytest::round($i); print $i == 0.0 ? "ok 7" : "not ok 7", "\n"; |
354 | $i = 0.5; &Mytest::round($i); print $i == 1.0 ? "ok 8" : "not ok 8", "\n"; |
355 | $i = 1.2; &Mytest::round($i); print $i == 1.0 ? "ok 9" : "not ok 9", "\n"; |
c07a80fd |
356 | |
360e660c |
357 | Running "C<make test>" should now print out that all nine tests are okay. |
4633a7c4 |
358 | |
360e660c |
359 | Notice that in these new test cases, the argument passed to round was a |
360 | scalar variable. You might be wondering if you can round a constant or |
361 | literal. To see what happens, temporarily add the following line to test.pl: |
4633a7c4 |
362 | |
791fa977 |
363 | &Mytest::round(3); |
4633a7c4 |
364 | |
360e660c |
365 | Run "C<make test>" and notice that Perl dies with a fatal error. Perl won't |
366 | let you change the value of constants! |
4633a7c4 |
367 | |
360e660c |
368 | =head2 What's new here? |
4633a7c4 |
369 | |
360e660c |
370 | =over 4 |
4633a7c4 |
371 | |
360e660c |
372 | =item * |
4633a7c4 |
373 | |
360e660c |
374 | We've made some changes to Makefile.PL. In this case, we've specified an |
375 | extra library to be linked into the extension's shared library, the math |
376 | library libm in this case. We'll talk later about how to write XSUBs that |
377 | can call every routine in a library. |
4633a7c4 |
378 | |
360e660c |
379 | =item * |
380 | |
381 | The value of the function is not being passed back as the function's return |
382 | value, but by changing the value of the variable that was passed into the |
383 | function. You might have guessed that when you saw that the return value |
384 | of round is of type "void". |
385 | |
386 | =back |
387 | |
388 | =head2 Input and Output Parameters |
4633a7c4 |
389 | |
360e660c |
390 | You specify the parameters that will be passed into the XSUB on the line(s) |
391 | after you declare the function's return value and name. Each input parameter |
392 | line starts with optional white space, and may have an optional terminating |
393 | semicolon. |
4633a7c4 |
394 | |
360e660c |
395 | The list of output parameters occurs at the very end of the function, just |
396 | before after the OUTPUT: directive. The use of RETVAL tells Perl that you |
397 | wish to send this value back as the return value of the XSUB function. In |
398 | Example 3, we wanted the "return value" placed in the original variable |
399 | which we passed in, so we listed it (and not RETVAL) in the OUTPUT: section. |
4633a7c4 |
400 | |
360e660c |
401 | =head2 The XSUBPP Program |
402 | |
403 | The xsubpp program takes the XS code in the .xs file and translates it into |
4633a7c4 |
404 | C code, placing it in a file whose suffix is .c. The C code created makes |
405 | heavy use of the C functions within Perl. |
406 | |
360e660c |
407 | =head2 The TYPEMAP file |
4633a7c4 |
408 | |
360e660c |
409 | The xsubpp program uses rules to convert from Perl's data types (scalar, |
410 | array, etc.) to C's data types (int, char, etc.). These rules are stored |
4633a7c4 |
411 | in the typemap file ($PERLLIB/ExtUtils/typemap). This file is split into |
412 | three parts. |
413 | |
360e660c |
414 | The first section maps various C data types to a name, which corresponds |
415 | somewhat with the various Perl types. The second section contains C code |
416 | which xsubpp uses to handle input parameters. The third section contains |
417 | C code which xsubpp uses to handle output parameters. |
4633a7c4 |
418 | |
360e660c |
419 | Let's take a look at a portion of the .c file created for our extension. |
420 | The file name is Mytest.c: |
4633a7c4 |
421 | |
791fa977 |
422 | XS(XS_Mytest_round) |
4633a7c4 |
423 | { |
424 | dXSARGS; |
c07a80fd |
425 | if (items != 1) |
791fa977 |
426 | croak("Usage: Mytest::round(arg)"); |
4633a7c4 |
427 | { |
c07a80fd |
428 | double arg = (double)SvNV(ST(0)); /* XXXXX */ |
4633a7c4 |
429 | if (arg > 0.0) { |
430 | arg = floor(arg + 0.5); |
431 | } else if (arg < 0.0) { |
432 | arg = ceil(arg - 0.5); |
c07a80fd |
433 | } else { |
434 | arg = 0.0; |
4633a7c4 |
435 | } |
360e660c |
436 | sv_setnv(ST(0), (double)arg); /* XXXXX */ |
4633a7c4 |
437 | } |
438 | XSRETURN(1); |
439 | } |
4633a7c4 |
440 | |
360e660c |
441 | Notice the two lines commented with "XXXXX". If you check the first section |
442 | of the typemap file, you'll see that doubles are of type T_DOUBLE. In the |
4633a7c4 |
443 | INPUT section, an argument that is T_DOUBLE is assigned to the variable |
444 | arg by calling the routine SvNV on something, then casting it to double, |
445 | then assigned to the variable arg. Similarly, in the OUTPUT section, |
ef50df4b |
446 | once arg has its final value, it is passed to the sv_setnv function to |
447 | be passed back to the calling subroutine. These two functions are explained |
448 | in L<perlguts>; we'll talk more later about what that "ST(0)" means in the |
449 | section on the argument stack. |
4633a7c4 |
450 | |
360e660c |
451 | =head2 Warning about Output Arguments |
4633a7c4 |
452 | |
c07a80fd |
453 | In general, it's not a good idea to write extensions that modify their input |
360e660c |
454 | parameters, as in Example 3. Instead, you should probably return multiple |
455 | values in an array and let the caller handle them (we'll do this in a later |
456 | example). However, in order to better accomodate calling pre-existing C |
457 | routines, which often do modify their input parameters, this behavior is |
458 | tolerated. |
791fa977 |
459 | |
460 | =head2 EXAMPLE 4 |
461 | |
68dc0745 |
462 | In this example, we'll now begin to write XSUBs that will interact with |
360e660c |
463 | pre-defined C libraries. To begin with, we will build a small library of |
791fa977 |
464 | our own, then let h2xs write our .pm and .xs files for us. |
465 | |
466 | Create a new directory called Mytest2 at the same level as the directory |
467 | Mytest. In the Mytest2 directory, create another directory called mylib, |
468 | and cd into that directory. |
469 | |
470 | Here we'll create some files that will generate a test library. These will |
471 | include a C source file and a header file. We'll also create a Makefile.PL |
472 | in this directory. Then we'll make sure that running make at the Mytest2 |
473 | level will automatically run this Makefile.PL file and the resulting Makefile. |
474 | |
9693b09d |
475 | In the mylib directory, create a file mylib.h that looks like this: |
791fa977 |
476 | |
477 | #define TESTVAL 4 |
478 | |
479 | extern double foo(int, long, const char*); |
480 | |
481 | Also create a file mylib.c that looks like this: |
482 | |
483 | #include <stdlib.h> |
484 | #include "./mylib.h" |
360e660c |
485 | |
791fa977 |
486 | double |
360e660c |
487 | foo(int a, long b, const char *c) |
791fa977 |
488 | { |
489 | return (a + b + atof(c) + TESTVAL); |
490 | } |
491 | |
492 | And finally create a file Makefile.PL that looks like this: |
493 | |
494 | use ExtUtils::MakeMaker; |
495 | $Verbose = 1; |
496 | WriteMakefile( |
360e660c |
497 | NAME => 'Mytest2::mylib', |
498 | SKIP => [qw(all static static_lib dynamic dynamic_lib)], |
499 | clean => {'FILES' => 'libmylib$(LIBEEXT)'}, |
791fa977 |
500 | ); |
501 | |
502 | |
8227f81c |
503 | sub MY::top_targets { |
791fa977 |
504 | ' |
505 | all :: static |
506 | |
360e660c |
507 | pure_all :: static |
508 | |
791fa977 |
509 | static :: libmylib$(LIB_EXT) |
510 | |
511 | libmylib$(LIB_EXT): $(O_FILES) |
512 | $(AR) cr libmylib$(LIB_EXT) $(O_FILES) |
513 | $(RANLIB) libmylib$(LIB_EXT) |
514 | |
515 | '; |
516 | } |
517 | |
360e660c |
518 | Make sure you use a tab and not spaces on the lines beginning with "$(AR)" |
519 | and "$(RANLIB)". Make will not function properly if you use spaces. |
520 | It has also been reported that the "cr" argument to $(AR) is unnecessary |
521 | on Win32 systems. |
522 | |
791fa977 |
523 | We will now create the main top-level Mytest2 files. Change to the directory |
524 | above Mytest2 and run the following command: |
525 | |
d9d2a7fb |
526 | % h2xs -O -n Mytest2 ./Mytest2/mylib/mylib.h |
791fa977 |
527 | |
528 | This will print out a warning about overwriting Mytest2, but that's okay. |
529 | Our files are stored in Mytest2/mylib, and will be untouched. |
530 | |
531 | The normal Makefile.PL that h2xs generates doesn't know about the mylib |
532 | directory. We need to tell it that there is a subdirectory and that we |
360e660c |
533 | will be generating a library in it. Let's add the argument MYEXTLIB to |
534 | the WriteMakefile call so that it looks like this: |
4633a7c4 |
535 | |
360e660c |
536 | WriteMakefile( |
537 | 'NAME' => 'Mytest2', |
538 | 'VERSION_FROM' => 'Mytest2.pm', # finds $VERSION |
539 | 'LIBS' => [''], # e.g., '-lm' |
540 | 'DEFINE' => '', # e.g., '-DHAVE_SOMETHING' |
541 | 'INC' => '', # e.g., '-I/usr/include/other' |
542 | 'MYEXTLIB' => 'mylib/libmylib$(LIB_EXT)', |
543 | ); |
791fa977 |
544 | |
360e660c |
545 | and then at the end add a subroutine (which will override the pre-existing |
546 | subroutine). Remember to use a tab character to indent the line beginning |
547 | with "cd"! |
791fa977 |
548 | |
549 | sub MY::postamble { |
550 | ' |
551 | $(MYEXTLIB): mylib/Makefile |
360e660c |
552 | cd mylib && $(MAKE) $(PASSTHRU) |
791fa977 |
553 | '; |
554 | } |
555 | |
791fa977 |
556 | Let's also fix the MANIFEST file so that it accurately reflects the contents |
557 | of our extension. The single line that says "mylib" should be replaced by |
558 | the following three lines: |
559 | |
560 | mylib/Makefile.PL |
561 | mylib/mylib.c |
562 | mylib/mylib.h |
563 | |
564 | To keep our namespace nice and unpolluted, edit the .pm file and change |
77ca0c92 |
565 | the variable C<@EXPORT> to C<@EXPORT_OK>. Finally, in the |
d9d2a7fb |
566 | .xs file, edit the #include line to read: |
791fa977 |
567 | |
568 | #include "mylib/mylib.h" |
569 | |
570 | And also add the following function definition to the end of the .xs file: |
571 | |
572 | double |
573 | foo(a,b,c) |
574 | int a |
575 | long b |
576 | const char * c |
360e660c |
577 | OUTPUT: |
791fa977 |
578 | RETVAL |
579 | |
580 | Now we also need to create a typemap file because the default Perl doesn't |
360e660c |
581 | currently support the const char * type. Create a file called typemap in |
582 | the Mytest2 directory and place the following in it: |
791fa977 |
583 | |
584 | const char * T_PV |
585 | |
586 | Now run perl on the top-level Makefile.PL. Notice that it also created a |
360e660c |
587 | Makefile in the mylib directory. Run make and watch that it does cd into |
791fa977 |
588 | the mylib directory and run make in there as well. |
589 | |
590 | Now edit the test.pl script and change the BEGIN block to print "1..4", |
591 | and add the following lines to the end of the script: |
592 | |
593 | print &Mytest2::foo(1, 2, "Hello, world!") == 7 ? "ok 2\n" : "not ok 2\n"; |
594 | print &Mytest2::foo(1, 2, "0.0") == 7 ? "ok 3\n" : "not ok 3\n"; |
595 | print abs(&Mytest2::foo(0, 0, "-3.4") - 0.6) <= 0.01 ? "ok 4\n" : "not ok 4\n"; |
596 | |
360e660c |
597 | (When dealing with floating-point comparisons, it is best to not check for |
598 | equality, but rather that the difference between the expected and actual |
599 | result is below a certain amount (called epsilon) which is 0.01 in this case) |
791fa977 |
600 | |
360e660c |
601 | Run "C<make test>" and all should be well. |
791fa977 |
602 | |
360e660c |
603 | =head2 What has happened here? |
791fa977 |
604 | |
605 | Unlike previous examples, we've now run h2xs on a real include file. This |
606 | has caused some extra goodies to appear in both the .pm and .xs files. |
607 | |
84dc3c4d |
608 | =over 4 |
609 | |
791fa977 |
610 | =item * |
611 | |
360e660c |
612 | In the .xs file, there's now a #include directive with the absolute path to |
613 | the mylib.h header file. We changed this to a relative path so that we |
614 | could move the extension directory if we wanted to. |
791fa977 |
615 | |
616 | =item * |
617 | |
618 | There's now some new C code that's been added to the .xs file. The purpose |
619 | of the C<constant> routine is to make the values that are #define'd in the |
360e660c |
620 | header file accessible by the Perl script (by calling either C<TESTVAL> or |
621 | C<&Mytest2::TESTVAL>). There's also some XS code to allow calls to the |
791fa977 |
622 | C<constant> routine. |
623 | |
624 | =item * |
625 | |
360e660c |
626 | The .pm file originally exported the name C<TESTVAL> in the C<@EXPORT> array. |
627 | This could lead to name clashes. A good rule of thumb is that if the #define |
628 | is only going to be used by the C routines themselves, and not by the user, |
629 | they should be removed from the C<@EXPORT> array. Alternately, if you don't |
630 | mind using the "fully qualified name" of a variable, you could move most |
631 | or all of the items from the C<@EXPORT> array into the C<@EXPORT_OK> array. |
791fa977 |
632 | |
d9d2a7fb |
633 | =item * |
634 | |
360e660c |
635 | If our include file had contained #include directives, these would not have |
636 | been processed by h2xs. There is no good solution to this right now. |
d9d2a7fb |
637 | |
360e660c |
638 | =item * |
791fa977 |
639 | |
640 | We've also told Perl about the library that we built in the mylib |
360e660c |
641 | subdirectory. That required only the addition of the C<MYEXTLIB> variable |
791fa977 |
642 | to the WriteMakefile call and the replacement of the postamble subroutine |
643 | to cd into the subdirectory and run make. The Makefile.PL for the |
644 | library is a bit more complicated, but not excessively so. Again we |
645 | replaced the postamble subroutine to insert our own code. This code |
360e660c |
646 | simply specified that the library to be created here was a static archive |
647 | library (as opposed to a dynamically loadable library) and provided the |
791fa977 |
648 | commands to build it. |
4633a7c4 |
649 | |
360e660c |
650 | =back |
651 | |
652 | =head2 More about XSUBPP |
4633a7c4 |
653 | |
791fa977 |
654 | With the completion of Example 4, we now have an easy way to simulate some |
c07a80fd |
655 | real-life libraries whose interfaces may not be the cleanest in the world. |
656 | We shall now continue with a discussion of the arguments passed to the |
657 | xsubpp compiler. |
4633a7c4 |
658 | |
360e660c |
659 | When you specify arguments to routines in the .xs file, you are really |
660 | passing three pieces of information for each argument listed. The first |
661 | piece is the order of that argument relative to the others (first, second, |
662 | etc). The second is the type of argument, and consists of the type |
663 | declaration of the argument (e.g., int, char*, etc). The third piece is |
664 | the exact way in which the argument should be used in the call to the |
665 | library function from this XSUB. This would mean whether or not to place |
666 | a "&" before the argument or not, meaning the argument expects to be |
667 | passed the address of the specified data type. |
4633a7c4 |
668 | |
c07a80fd |
669 | There is a difference between the two arguments in this hypothetical function: |
4633a7c4 |
670 | |
4633a7c4 |
671 | int |
c07a80fd |
672 | foo(a,b) |
673 | char &a |
674 | char * b |
4633a7c4 |
675 | |
c07a80fd |
676 | The first argument to this function would be treated as a char and assigned |
677 | to the variable a, and its address would be passed into the function foo. |
678 | The second argument would be treated as a string pointer and assigned to the |
679 | variable b. The I<value> of b would be passed into the function foo. The |
680 | actual call to the function foo that xsubpp generates would look like this: |
4633a7c4 |
681 | |
c07a80fd |
682 | foo(&a, b); |
4633a7c4 |
683 | |
360e660c |
684 | Xsubpp will parse the following function argument lists identically: |
791fa977 |
685 | |
686 | char &a |
687 | char&a |
688 | char & a |
689 | |
690 | However, to help ease understanding, it is suggested that you place a "&" |
691 | next to the variable name and away from the variable type), and place a |
692 | "*" near the variable type, but away from the variable name (as in the |
360e660c |
693 | call to foo above). By doing so, it is easy to understand exactly what |
694 | will be passed to the C function -- it will be whatever is in the "last |
695 | column". |
4633a7c4 |
696 | |
c07a80fd |
697 | You should take great pains to try to pass the function the type of variable |
698 | it wants, when possible. It will save you a lot of trouble in the long run. |
4633a7c4 |
699 | |
360e660c |
700 | =head2 The Argument Stack |
4633a7c4 |
701 | |
c07a80fd |
702 | If we look at any of the C code generated by any of the examples except |
703 | example 1, you will notice a number of references to ST(n), where n is |
360e660c |
704 | usually 0. "ST" is actually a macro that points to the n'th argument |
705 | on the argument stack. ST(0) is thus the first argument on the stack and |
706 | therefore the first argument passed to the XSUB, ST(1) is the second |
707 | argument, and so on. |
4633a7c4 |
708 | |
184e9718 |
709 | When you list the arguments to the XSUB in the .xs file, that tells xsubpp |
c07a80fd |
710 | which argument corresponds to which of the argument stack (i.e., the first |
711 | one listed is the first argument, and so on). You invite disaster if you |
712 | do not list them in the same order as the function expects them. |
4633a7c4 |
713 | |
360e660c |
714 | The actual values on the argument stack are pointers to the values passed |
715 | in. When an argument is listed as being an OUTPUT value, its corresponding |
716 | value on the stack (i.e., ST(0) if it was the first argument) is changed. |
717 | You can verify this by looking at the C code generated for Example 3. |
718 | The code for the round() XSUB routine contains lines that look like this: |
719 | |
720 | double arg = (double)SvNV(ST(0)); |
721 | /* Round the contents of the variable arg */ |
722 | sv_setnv(ST(0), (double)arg); |
723 | |
724 | The arg variable is initially set by taking the value from ST(0), then is |
725 | stored back into ST(0) at the end of the routine. |
726 | |
727 | =head2 Extending your Extension |
4633a7c4 |
728 | |
c07a80fd |
729 | Sometimes you might want to provide some extra methods or subroutines |
730 | to assist in making the interface between Perl and your extension simpler |
731 | or easier to understand. These routines should live in the .pm file. |
732 | Whether they are automatically loaded when the extension itself is loaded |
360e660c |
733 | or only loaded when called depends on where in the .pm file the subroutine |
734 | definition is placed. You can also consult L<Autoloader> for an alternate |
735 | way to store and load your extra subroutines. |
4633a7c4 |
736 | |
360e660c |
737 | =head2 Documenting your Extension |
4633a7c4 |
738 | |
c07a80fd |
739 | There is absolutely no excuse for not documenting your extension. |
740 | Documentation belongs in the .pm file. This file will be fed to pod2man, |
360e660c |
741 | and the embedded documentation will be converted to the man page format, |
c07a80fd |
742 | then placed in the blib directory. It will be copied to Perl's man |
743 | page directory when the extension is installed. |
4633a7c4 |
744 | |
c07a80fd |
745 | You may intersperse documentation and Perl code within the .pm file. |
746 | In fact, if you want to use method autoloading, you must do this, |
747 | as the comment inside the .pm file explains. |
4633a7c4 |
748 | |
c07a80fd |
749 | See L<perlpod> for more information about the pod format. |
4633a7c4 |
750 | |
360e660c |
751 | =head2 Installing your Extension |
4633a7c4 |
752 | |
c07a80fd |
753 | Once your extension is complete and passes all its tests, installing it |
360e660c |
754 | is quite simple: you simply run "make install". You will either need |
c07a80fd |
755 | to have write permission into the directories where Perl is installed, |
756 | or ask your system administrator to run the make for you. |
4633a7c4 |
757 | |
360e660c |
758 | Alternately, you can specify the exact directory to place the extension's |
759 | files by placing a "PREFIX=/destination/directory" after the make install. |
760 | (or in between the make and install if you have a brain-dead version of make). |
761 | This can be very useful if you are building an extension that will eventually |
762 | be distributed to multiple systems. You can then just archive the files in |
763 | the destination directory and distribute them to your destination systems. |
764 | |
765 | =head2 EXAMPLE 5 |
766 | |
767 | In this example, we'll do some more work with the argument stack. The |
768 | previous examples have all returned only a single value. We'll now |
769 | create an extension that returns an array. |
770 | |
771 | This extension is very Unix-oriented (struct statfs and the statfs system |
772 | call). If you are not running on a Unix system, you can substitute for |
773 | statfs any other function that returns multiple values, you can hard-code |
774 | values to be returned to the caller (although this will be a bit harder |
775 | to test the error case), or you can simply not do this example. If you |
776 | change the XSUB, be sure to fix the test cases to match the changes. |
777 | |
778 | Return to the Mytest directory and add the following code to the end of |
779 | Mytest.xs: |
780 | |
781 | void |
782 | statfs(path) |
783 | char * path |
784 | PREINIT: |
785 | int i; |
786 | struct statfs buf; |
787 | |
788 | PPCODE: |
789 | i = statfs(path, &buf); |
790 | if (i == 0) { |
791 | XPUSHs(sv_2mortal(newSVnv(buf.f_bavail))); |
792 | XPUSHs(sv_2mortal(newSVnv(buf.f_bfree))); |
793 | XPUSHs(sv_2mortal(newSVnv(buf.f_blocks))); |
794 | XPUSHs(sv_2mortal(newSVnv(buf.f_bsize))); |
795 | XPUSHs(sv_2mortal(newSVnv(buf.f_ffree))); |
796 | XPUSHs(sv_2mortal(newSVnv(buf.f_files))); |
797 | XPUSHs(sv_2mortal(newSVnv(buf.f_type))); |
798 | XPUSHs(sv_2mortal(newSVnv(buf.f_fsid[0]))); |
799 | XPUSHs(sv_2mortal(newSVnv(buf.f_fsid[1]))); |
800 | } else { |
801 | XPUSHs(sv_2mortal(newSVnv(errno))); |
802 | } |
803 | |
804 | You'll also need to add the following code to the top of the .xs file, just |
805 | after the include of "XSUB.h": |
806 | |
807 | #include <sys/vfs.h> |
808 | |
809 | Also add the following code segment to test.pl while incrementing the "1..9" |
810 | string in the BEGIN block to "1..11": |
811 | |
812 | @a = &Mytest::statfs("/blech"); |
813 | print ((scalar(@a) == 1 && $a[0] == 2) ? "ok 10\n" : "not ok 10\n"); |
814 | @a = &Mytest::statfs("/"); |
815 | print scalar(@a) == 9 ? "ok 11\n" : "not ok 11\n"; |
816 | |
817 | =head2 New Things in this Example |
818 | |
819 | This example added quite a few new concepts. We'll take them one at a time. |
820 | |
821 | =over 4 |
822 | |
823 | =item * |
824 | |
825 | The PREINIT: directive contains code that will be placed immediately after |
826 | variable declaration and before the argument stack is decoded. Some compilers |
827 | cannot handle variable declarations at arbitrary locations inside a function, |
828 | so this is usually the best way to declare local variables needed by the XSUB. |
829 | |
830 | =item * |
831 | |
832 | This routine also returns a different number of arguments depending on the |
833 | success or failure of the call to statfs. If there is an error, the error |
834 | number is returned as a single-element array. If the call is successful, |
835 | then a 9-element array is returned. Since only one argument is passed into |
836 | this function, we need room on the stack to hold the 9 values which may be |
837 | returned. |
838 | |
839 | We do this by using the PPCODE: directive, rather than the CODE: directive. |
840 | This tells xsubpp that we will be managing the return values that will be |
841 | put on the argument stack by ourselves. |
842 | |
843 | =item * |
844 | |
845 | When we want to place values to be returned to the caller onto the stack, |
846 | we use the series of macros that begin with "XPUSH". There are five |
847 | different versions, for placing integers, unsigned integers, doubles, |
848 | strings, and Perl scalars on the stack. In our example, we placed a |
849 | Perl scalar onto the stack. |
850 | |
851 | The XPUSH* macros will automatically extend the return stack to prevent |
852 | it from being overrun. You push values onto the stack in the order you |
853 | want them seen by the calling program. |
854 | |
855 | =item * |
856 | |
857 | The values pushed onto the return stack of the XSUB are actually mortal SV's. |
858 | They are made mortal so that once the values are copied by the calling |
859 | program, the SV's that held the returned values can be deallocated. |
860 | If they were not mortal, then they would continue to exist after the XSUB |
861 | routine returned, but would not be accessible. This is a memory leak. |
862 | |
863 | =back |
864 | |
865 | =head2 EXAMPLE 6 (Coming Soon) |
866 | |
867 | Passing in and returning references to arrays and/or hashes |
868 | |
869 | =head2 EXAMPLE 7 (Coming Soon) |
870 | |
871 | XPUSH args AND set RETVAL AND assign return value to array |
872 | |
873 | =head2 EXAMPLE 8 (Coming Soon) |
874 | |
875 | Setting $! |
876 | |
877 | =head2 EXAMPLE 9 (Coming Soon) |
878 | |
879 | Getting fd's from filehandles |
880 | |
881 | =head2 Troubleshooting these Examples |
882 | |
883 | As mentioned at the top of this document, if you are having problems with |
884 | these example extensions, you might see if any of these help you. |
885 | |
886 | =over 4 |
887 | |
888 | =item * |
889 | |
890 | In versions of 5.002 prior to the gamma version, the test script in Example |
891 | 1 will not function properly. You need to change the "use lib" line to |
892 | read: |
893 | |
894 | use lib './blib'; |
895 | |
896 | =item * |
897 | |
898 | In versions of 5.002 prior to version 5.002b1h, the test.pl file was not |
899 | automatically created by h2xs. This means that you cannot say "make test" |
900 | to run the test script. You will need to add the following line before the |
901 | "use extension" statement: |
902 | |
903 | use lib './blib'; |
904 | |
905 | =item * |
906 | |
907 | In versions 5.000 and 5.001, instead of using the above line, you will need |
908 | to use the following line: |
909 | |
910 | BEGIN { unshift(@INC, "./blib") } |
911 | |
912 | =item * |
913 | |
914 | This document assumes that the executable named "perl" is Perl version 5. |
915 | Some systems may have installed Perl version 5 as "perl5". |
916 | |
917 | =back |
918 | |
919 | =head1 See also |
4633a7c4 |
920 | |
c07a80fd |
921 | For more information, consult L<perlguts>, L<perlxs>, L<perlmod>, |
922 | and L<perlpod>. |
4633a7c4 |
923 | |
360e660c |
924 | =head1 Author |
4633a7c4 |
925 | |
9607fc9c |
926 | Jeff Okamoto <F<okamoto@corp.hp.com>> |
4633a7c4 |
927 | |
c07a80fd |
928 | Reviewed and assisted by Dean Roehrich, Ilya Zakharevich, Andreas Koenig, |
929 | and Tim Bunce. |
4633a7c4 |
930 | |
c07a80fd |
931 | =head2 Last Changed |
4633a7c4 |
932 | |
360e660c |
933 | 1999/5/25 |