Getting Started with Inline::C

Chapter 10 - Writing C Modules with Inline::C
by?Sam Tregar?
Apress ? 2002
has companion web siteCompanion Web Site

Writing a module with Inline::C is a lot like writing an XS module with no XS. As such, you can get started with h2xs the same was as you would with a pure Perl module. To generate a skeleton for Gnome::MIME, I use the following command:

 h2xs -XA -n Gnome::MIME 

This creates the same files as you examined in Table 10-1). Since I'm using Inline::C, all the C code for the module will go in MIME.pm alongside the Perl code.

Table 10-1: Files Generated by h2xs -XA -n Gnome::MIME

File

Description


MIME.pm

The module file itself, which contains Perl code, C code, and POD documentation


Makefile.PL

A script that uses ExtUtils::MakeMaker to generate a Makefile


test.pl

A test script run when a user types "make test" or installs your module with the CPAN module


README

A quick description of your module and how to install it


Changes

A change log in which you can describe differences between versions of your module


MANIFEST

A list of all the files in your distribution

Modifying Makefile.PL

However, before I can get started, the generated Makefile.PL requires some modification to build an Inline::C module (see Listing 10-1).

Listing 10-1: Makefile.PL for Inline::C Version of Gnome::MIME

start example
 use Inline::MakeMaker; WriteInlineMakefile(                      NAME          => "Gnome::MIME",                      VERSION_FROM  => "MIME.pm",                      PREREQ_PM     => { Inline::C => 0.43 },                      AUTHOR        => 'Sam Tregar <sam@tregar.com>',                    ); 
end example

This file is considerably different from the version created for XS. First, it starts by using a different MakeMaker module:

 use Inline::MakeMaker; 

Also, it calls WriteInlineMakefile() rather than WriteMakefile(). Inline::C modules use a different MakeMaker to allow them to be compiled and installed just like XS modules rather than being compiled the first time they're used. Also, notice that Inline::C is listed as a requirement in PREREQ_PM:

 PREREQ_PM => { Inline::C => 0.43 }, 

A future version of Inline::C will make it possible to build modules that do not depend on Inline::C, but at least for version 0.43 users of Inline::C-based modules must also install Inline::C.

What's new isn't as notable as what's missing-the calls to gnome-config to set up LIBS and INC. This logic will still be needed by the module, but it will go in the module itself rather than living in the Makefile.PL.

Modifying MIME.pm

The configuration that was part of Makefile.PL in the XS version is now part of MIME.pm (Listing 10-2).

Listing 10-2: MIME.pm with a Single C-Function Wrapper

start example
 package Gnome::MIME; our $VERSION = "0.01"; use Inline C       => 'DATA',            NAME    => "Gnome::MIME",            VERSION => "0.01",            LIBS    => 'gnome-config gnome --libs',            INC     => 'gnome-config gnome --cflags'; 1; __DATA__ __C__ #include <gnome.h> char * file_type (char *filename) {   return gnome_mime_type(filename); } 
end example

This module uses Inline::C differently from the inline.pl script shown at the beginning of the chapter. Instead of passing the C code in a string, this code points Inline::C at the __DATA__ section where the code will follow a __C__ identifier:

 use Inline C         => 'DATA', 

The next lines specify the name and version of the module. This information is slightly redundant, but Inline::C uses these options as a cue that it's building C code for a module and not a script:

      NAME    => "Gnome::MIME",      VERSION => "0.01", 

Next comes the configuration data that the XS version set up in Makefile.PL, LIBS, and INC:

     LIBS    => 'gnome-config gnome --libs',     INC     => 'gnome-config gnome --cflags'; 

The C code is placed after the __DATA__ symbol. Below __DATA__, __C__ marks the start of the C code:

 __DATA__ __C__ #include <gnome.h> char * file_type (char *filename) {   return gnome_mime_type(filename); } 

I'll discuss the actual C code in the next section.

A First Inlined Function

Just as in the first XS example in the last chapter, I'll start with the gnome_mime_type() function. This function takes a filename as an argument and returns a string containing the MIME type of the filename. It has the following signature:

 const char * gnome_mime_type(const gchar *filename); 

One way to wrap this function is shown in Listing 10-2, with the function file_type():

 char * file_type (char *filename) {   return gnome_mime_type(filename); } 

With this function in place, test.pl can be written:

 use Test::More 'no_plan'; BEGIN { use_ok('Gnome::MIME'); } # test some simple mime-file_type recognitions is(Gnome::MIME::file_type("foo.gif"), 'image/gif', "recognizes .gif"); is(Gnome::MIME::file_type("foo.jpg"), 'image/jpeg', "recognizes .jpg"); is(Gnome::MIME::file_type("foo.html"), 'text/html', "recognizes .html"); 

The module can then be built and tested:

 $ perl Makefile.PL && make && make test Checking if your kit is complete... Looks good Writing Makefile for Gnome::MIME cp MIME.pm blib/lib/Gnome/MIME.pm /usr/local/bin/perl -Mblib -MInline=_INSTALL_ -MGnome::MIME -e1 0.01 blib/arch Using /home/sam/Gnome/MIME/blib PERL_DL_NONLAZY=1 /usr/local/bin/perl -Iblib/arch -Iblib/lib \   -I/usr/local/lib/perl5/5.6.1/i686-linux -I/usr/local/lib/perl5/5.6.1 test.pl ok 1 - use Gnome::MIME; ok 2 - recognizes .gif ok 3 - recognizes .jpg ok 4 - recognizes .html 1..4 

That's all there is to it! No extra files; just a pure C function in the body of the module.

Notice that this case is different from the starting point with XS, where the simplest XSUB was one without any code at all. XS and Inline::C are tuned for different uses. XS is tuned to produce direct mappings from C function signatures to Perl functions. Inline::C prefers full C functions. However, just as XS has CODE and PPCODE to support full C functions, Inline::C has facilities for generating wrappers from function signatures. The difference is more one of emphasis than of capability.



Writing Perl Modules for CPAN
Writing Perl Modules for CPAN
ISBN: 159059018X
EAN: 2147483647
Year: 2002
Pages: 110
Authors: Sam Tregar

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net