perl XS adventures, episode 1

Perl XS is easy if you read the docs in the proper order. What is the proper order ? I have no idea, I kept at it until it clicked. Well, not all of it clicked, just enough to get some results.

Summary so far: managed to persuade perl to run my code from the .xs file, to compile my .c files and to call code in the .c files from the .xs file.

To have it work I kept it simple. I tried the not-simple version and you don't want to know the story.

Hints for the inpatient

Quick hints

• man 2 and man 3 are your best friends, if you don't know this already; for example

  man 2 readdir

  or

  man 3 strcat

• read perlguts before perlapi; better, do not attempt to read perlapi end-to-end, just consult it when you need
• normal C code in custom .c and .h files, which all got to the root of the project (where Makefile.PL is); it is possible to put them some other place but I have not found out how to change Makefile.PL to deal with it.
• include .h files in the .xs file
• the code that uses Perl types and functions stays in the .xs file; Perl-independent C code can go before the

  MODULE = My::Module  PACKAGE = My::Module

  line
  
• extra libraries added in the Makefile as obiect files in here

  OBJECT            => '$(BASEEXT)$(OBJ_EXT) blah.o', 
  

  or even better

  OBJECT            => '$(BASEEXT)$(OBJ_EXT) blah$(OBJ_EXT)'

• to raise exceptions use

  croak(const char * blah)

  instead of exit(1) in the code in the .xs files

How to change the generated Makefile

based on http://www.perlmonks.org/?node_id=664066

Add a new compilation target

sub postamble {
    # this should be empty 
    my $inherited = shift->SUPER::postamble(@_);

    my $extra = q{
clean_temp_files :
 if [ -d /tmp/blah ]; then rm -rf /tmp/blah; fi
};
    return $inherited . "\n" . $extra;
}

Modify an existing compilation target

I think all the sections in the generated Makefile can be intercepted and modified, but so far I have tried only with clean:

sub clean {
  my $inherited = shift->SUPER::clean(@_);
  $inherited =~ s/clean :: clean_subdirs/clean :: clean_subdirs clean_temp_files/;
  return $inherited;
}

Step by step instructions for the very patient XS Mechanics or XS Fun.