Perl 对 C 的扩展接口

XS 语言是一种用来在 Perl 和需要在 Perl 内使用的 C 代码（或者 C 库）之间创建扩展的接口描述文件格式。XS 接口为 C 库链接创建了一个静态链接到 Perl 或者能被 Perl 动态导入的新库。本文的主要目的是介绍如何在 Unix 环境下编写 XS 接口并成功通过编译，从而实现 Perl 对 C 的扩展，提高代码重用率。

引言

本文面向 Perl 和 C 的开发人员，旨在通过对 Perl 与 C 之间的 XS 扩展接口的介绍，让读者了解到通过 Perl 调用 C 函数的一种方法。为了更好的理解本文，读者需要具备一定的 Perl 和 C 编程经验，并对 Unix 环境下库文件的编译过程和 Makefile 语法有所了解。

什么是 XS 语言

XS 是一个用来在 Perl 和需要在 Perl 内使用的 C 代码（或者 C 库）之间创建扩展的接口描述文件格式。XS 接口为 C 库链接创建了一个静态链接到 Perl 或者能被 Perl 动态导入的新库。XS 接口描述是用 XS 语言写的，是 Perl 扩展接口的核心部分。

当 Perl 代码调用 C 函数时，XS 从 Perl 堆栈中获取参数，将这些参数转化为 C 函数所要求的正确格式，调用相应的 C 函数，并将返回值转化为 Perl 的参数格式，压入 Perl 堆栈供程序读取，或者直接修改 Perl 所提供的变量值。

由于 Perl 提供了比 C 更为自由的变量定义和调用规则，在参数转换过程中，XS 还必须验证参数合法性，抛出异常（或返回 undef 或空值列表），根据参数的数目和类型的不同调用不同的 C 函数，提供面向对象接口等等。

XS 语言的编译器叫做 xsubpp，它为接口创建必要的数据结构和调用关系，xsubpp 根据 typemaps 来确定如何在 Perl 与 C 之间转换函数参数和返回值。标准 Perl 库自带的 typemap 定义了大部分常用的 C 变量类型，但一些特殊的数据结构和类型需要开发人员通过自定义的 typemap 来实现。

.XS 文件

XSUB 解析

XS 接口文件以 .xs 为后缀名，里面定义了 Perl 与 C 之间的接口函数。XSUB 是 XS 接口的基本结构单元，通过 xsubpp 编译后，每个 XSUB 都为相应的 C 函数提供了 Perl 与 C 之间的调用接口。

清单 1 . 一个简单的 .xs 文件

				  
 #include "EXTERN.h"
 #include "perl.h"
 #include "XSUB.h"
       
 MODULE = TEST   PACKAGE = TEST 
 void 
 hello() 
 CODE: 
 printf("Hello,world!/n");

其中前三个 #include 声明：EXTERN.h，perl.h 和 XSUB.h 应该始终出现在每个 XS 文件的开头。其后是其他的头文件 #include 声明。

MODULE= 定义了该 XS 文件所属的 Perl 模块（.pm），同一个 .xs 文件中所有的 MODULE= 都应该保持一致。每个 MODULE= 之后则是对应的 XSUB 定义，直到文件结束或者下一个 MODULE= 语句。

PACKAGE= 定义了该函数所在的 Package，当同一个 .xs 文件需要被划分为多个 Package 时 PACKAGE= 则需要被显式指定。PACKAGE= 应该和 MODULE= 放在一起并紧随其后。

一个最简单的 XSUB 由三部分（section）组成：返回值定义；XSUB 函数名和参数名；以及参数类型。复杂的 XSUB 还包括其他部分，如 CODE:（代码段），IUPUT:（输入值），OUTPUT:（输出值）等等。其中返回值和函数名必须位于每个 XSUB 的开头，分行书写并左对齐顶格，其余部分格式则没有严格要求。

清单 2 .XSUB 格式

				  
 double sin(x)        double                 double 
 double x                sin(x)              sin(x) 
                       double x                double x 
  错误                  错误                  正确

Perl 变量堆栈和参数

Perl 变量堆栈（argument stack）用于存放发送给 XSUB 的参数值及其返回值。XSUB 可以通过宏 ST(x) 访问该堆栈，其中 ST(0) 为该堆栈的起始地址。

清单 3 . 操作 ST(x)

				  
 membername = (char*)SvPV(ST(2),na); 
 ST(0) = newSVpv("Hello World",0);

而宏 SP 代表当前 Perl 堆栈指针，当程序从 XSUB 返回时，处理堆栈上的数据。

清单 4 . 操作 SP

				  
 EXTEND(SP,2);

变量 RETVAL 是一个特殊的 C 变量，它的类型对应于 C 函数的返回值类型。xsubpp 编译器会自动为每个 non-void 返回值类型的函数声明该变量，用于存放被调用的 C 函数的返回值。通常情况下，RETVAL 会作为对应 XSUB 的返回值存放到 Perl 变量堆栈的 ST(0)。

清单 5 .RETVAL 变量

				  
 int 
 is_even(input) 
 int input 
 CODE: 
 RETVAL = (input % 2 == 0); 
 OUTPUT: 
 RETVAL

注意： 当 XSUB 返回值为 void 时，编译器不会为该函数声明 RETVAL 变量；当存在 PPCODE: 关键字时，不能对 RETVAL 变量进行操作，而应该直接操作对应的 Perl 变量堆栈 ST(x)。

XSUB 的一些关键字

OUTPUT: 关键字指定了当 XSUB 结束时应该返回给调用方 Perl 的参数值。在没有 CODE: 段和 PPCODE: 段时，RETVAL 变量会被自动指定为 OUTPUT 变量，否则需要显式指定 OUTPUT 变量。该关键字也能用于指定函数输入参数为 OUTPUT 变量，这在当函数体改变了某个输入参数值并希望将新值返回给调用方 Perl 的情况下十分有用。

清单 6 .C 函数原型

				  
 bool_t gettime(const char *host,time_t *timep);

其函数将指定 host 上的当前系统时间存入指针 timp 对应的地址中，同时返回布尔型状态值。

清单 7 . 对应的 XSUB 函数定义

				  
 bool_t 
 gettime(host,timep) 
	 char *host 
	 time_t &timep 
 OUTPUT: 
	 Timep

CODE: 关键字用于对相应的 C 函数做额外的操作处理，此时 RETVAL 变量仍被声明，但并不作为返回值，除非被 OUTPUT: 关键字显式指定。仍以上面的 C 函数 gettime (host,timep) 为例，如果在 Perl 代码中存在以下的调用：

Perl 代码调用

$status = gettime( "localhost",$timep );

其中 $status 和 $timep 都用于接收 C 函数的返回值，则需要对相应的 C 函数做额外的处理。

清单 9. 对应的 XSUB 函数定义

				  
 bool_t 
 gettime(host,timep) 
	 char *host 
	 time_t timep 
 CODE: 
	 RETVAL = gettime( host,&timep ); 
 OUTPUT: 
	 timep 
	 RETVAL

通过一元运算符 &，当 xsubpp 编译器调用 C 函数 gettime() 时，传给 C 函数的参数 &timep 是指向 time_t 的指针 time_t *，同时将得到的时间值存储在 timep 中返回给 Perl。

PPCODE: 关键字是对 CODE: 的补充，用于直接操作 Perl 变量堆栈。这在当 XSUB 存在多个返回值时十分有用。此时必须在 PPCODE: 中显式的将返回值列表压入堆栈顶。需要注意的是，在同一个 XSUB 中 CODE: 和 PPCODE: 不能同时出现。

PPCODE: 通常直接操作 SP，通过 PUSH*() 宏将返回值列表压入 Perl 堆栈，而不是将其作为返回值传送给 Perl，因此其函数返回值类型一般为 void，用于告诉 xsubpp 编译器不需要声明和创建 VETVAL 变量。

清单 10.PPCODE: 关键字

				  
 void 
 gettime(host) 
	 char *host 
 PREINIT: 
	 time_t  timep; 
	 bool_t  status; 
 PPCODE: 
	 status = gettime( host,&timep ); 
	 EXTEND(SP,2); 
	 PUSHs(sv_2mortal(newSViv(status))); 
	 PUSHs(sv_2mortal(newSViv(timep)));

通过 PUSH() 宏将 C 函数 gettime() 的返回值 status 和 timep 依次压入 Perl 堆栈，有了上面的 XSUB 定义，则在 Perl 代码中可以这样调用上面的 C 函数 gettime()。

Perl 代码调用

($status,$timep) = gettime("localhost");

编译 XS 文件

编译命令 h2xs

使用 h2xs 来编译并生成 XS 扩展接口所必要的系列文件。h2xs 用于根据 C 头文件 .h 生成相应的 Perl扩展，其扩展模块名字由 -n 参数指定，当没有 -n 参数时，则自动使用第一个 .h 头文件的名字，并将其首字母大写作为扩展模块的名字。

表 1. h2xs 常用参数

参数名	说明
-A --omit-autoload	忽略 autoload 机制
-O --overwrite-ok	允许覆盖已存在的扩展文件
-n --name=module_name	指定扩展模块的名字

更为详细和完整的参数列表可参阅相关文档 perldoc-h2xs。

生成的文件

当执行命令 “h2xs -A -n Mytest” 后，系统在当前目录下创建一个子目录 Mytest，并在其下生成一系列文件：MANIFEST，Makefile.PL，Mytest.pm，Mytest.xs，Mytest.t 和 Changes。

MANIFEST

MANIFEST 文件包含了在 Mytest 目录下创建的所有文件的名字。

清单 11 .MANIFEST 文件内容

				  
 Changes 
 Makefile.PL 
 MANIFEST 
 Mytest.xs 
 ppport.h 
 README 
 Mytest.t 
 lib/Mytest.pm 
 mylib/Makefile.PL 
 mylib/test.c 
 mylib/test.h

Changes

Changes 文件记录了扩展接口的创建以及后续的修改动作。

清单 12.Changes 文件内容

				  
 Revision history for Perl extension Mytest. 

 0.01  Tue Jun  2 15:23:11 2009 
 - original version; created by h2xs 1.23 with options 
	 -A -O -n Mytest ./Mytest/mylib/test.h

Makefile.PL

Makefile.PL 文件是一个 Perl 脚本，用于自动生成 Makefile，以创建扩展接口。当执行 “Perl Makefile.PL” 命令后，系统生成相应的 Makfile，然后执行 “make” 会在当前目录下生成 blib 子目录，用于存放将要使用到的共享库文件 (shared library)。

清单 13 . 一个简单的 Makefile.PL

				  
use ExtUtils::MakeMaker; 
 # See lib/ExtUtils/MakeMaker.pm for details of how to influence 
 # the contents of the Makefile that is written. 
 WriteMakefile( 
	 NAME         => 'Mytest',VERSION_FROM => 'Mytest.pm',# finds $VERSION 
	 LIBS         => [''],# e.g.,'-lm'
	 DEFINE       => '','-DHAVE_SOMETHING'
	 INC          => '','-I/usr/include/other'
 );

Mytest.pm

Mytest.pm 文件是一个模块文件，定义了 Perl 如何加载该扩展接口。当在 Perl 代码中出现 “use Mytest;” 时，Perl 会在 @INC 数组中定义的目录列表里搜索 Mytest.pm 并加载。然后 Perl 代码就可以直接调用 Mytest.xs 扩展中定义的 C 函数。

清单 14 .Mytest.pm 框架

				  
 package Mytest; 

 use 5.008008; 

 use strict; 
 use warnings; 

 require Exporter; 
 our @ISA = qw(Exporter); 
 our %EXPORT_TAGS = ( 'all' => [ qw( 
 )]); 

 our $VERSION = '0.01'; 
 require XSLoader; 
 XSLoader::load('Mytest',$VERSION); 

 # Preloaded methods go here. 
 1; 	
 __END__ 
 # Below is the stub of documentation for your module. You better edit it!

Mytest.xs
Mytest.xs 实现了 Perl 扩展接口，通过该接口 Perl 代码可以调用对应 C 文件中定义实现的函数。

Mytest.t

Mytest.t 文件是代码测试脚本，可以通过执行 “make test” 来测试扩展模块的编译是否正确。

清单 15 .Mytest.t 框架

				  
use Test::More tests => 4; 
 BEGIN { use_ok('Mytest') }; 

 # Insert your test code below,the Test::More module is use()ed here so read 
 # its man page ( perldoc Test::More ) for help writing this test script.

编译过程

通常一个 XS 扩展接口的编译过程为以下几步：

清单 16 . 编译步骤

				  
 perl Makefile.PL     
 make                   
 make test 
 make install

首先运行 ”perl Makefile.PL” 在当前目录生成 Makefile；然后运行 ”make” 编译并创建所需的库文件；之后用 ”make test” 测试编译结果是否正确；最后运行 ”make install” 将库文件安装到系统目录，至此整个编译过程结束。

一个 XS 实例

在当前目录创建一个子目录 Mytest，在 Mytest 目录下创建子目录 mylib，并将已写好的 C 头文件和源代码放在 mylib 目录下。

清单 17 . 头文件 test.h

				  
 #define TESTVAL 	 3 
 extern double 	 add(int,long); 
 extern int    max(int,int);

清单 18 . 源文件 test1.c

				  
 #include "./test.h"
 double add(int a,long b) 
 { 
 return (a + b + TESTVAL); 
 }

清单 19 . 源文件 test2.c

				  
 #include "./test.h"
 int max(int a,int b) 
 { 
 return ((a>b)? a:b); 
 }

在 Mytest/mylib 目录下创建 Makefile.PL 文件，以保证在 Mytest 目录运行 ”make” 时会自动调用该 Makefile.PL 并生成相应的 Makefile。

清单 20 .Mytest/mylib 目录下的 Makefile.PL

				  
use ExtUtils::MakeMaker; 
 $Verbose = 1; 
 WriteMakefile( 
 NAME   => 'Mytest::mylib',SKIP   => [qw(all static static_lib dynamic dynamic_lib)],clean  => {'FILES' => 'libmylib$(LIB_EXT)'},); 

 sub MY::top_targets { 
'
 all :: static 
 pure_all :: static 
 static ::  libmylib$(LIB_EXT) 
 libmylib$(LIB_EXT): $(O_FILES) 
 $(AR) cr libmylib$(LIB_EXT) $(O_FILES) 
 $(RANLIB) libmylib$(LIB_EXT) 
'; 
 }

在 MY::top_targets 中，通过 ar 将 mylib 子目录下的 test1.o 和 test2.o 编译为静态库 libmylib.a，并通过 ranlib 更新静态库 libmylib.a 的符号索引表。

注意： $(AR) 和 $(RANLIB) 前面应该是 ‘ Tab ’ 而不是空格，否则 Make 会报 “missing separator” 错误并终止编译。

在 Mytest 的上级目录中执行命令 “h2xs -A -O -n Mytest ./Mytest/mylib/test.h” 以生成扩展接口系列文件。
注意：Perl 会提示覆盖 Mytest 目录，并在 Mytest 中生成上节介绍的系列文件，这也是要将源文件放在 /Mytest/mylib/ 下的原因，以免被自动生成的文件覆盖。

Perl 在 Mytest 下自动生成的 Makefile.PL 并不知道子目录 mylib 的存在，因此需要修改该 Makefile.PL。

清单 21 . 修改 Mytest 目录下的 Makefile.PL

				  
 WriteMakefile( 
	 'NAME'         => 'Mytest','VERSION_FROM' => 'Mytest.pm',# finds $VERSION 
	 'LIBS'         => [''],'-lm'
	 'DEFINE'       => '','-DHAVE_SOMETHING'
	 'INC'          => '','-I/usr/include/other'
	 'MYEXTLIB'     => 'mylib/libmylib$(LIB_EXT)',);

指定了 MYEXTLIB 为 mylib 子目录下的 libmylib.a。

清单 22 . 在 Makefile.PL 文件的最后添加 MY::postamble 函数

				  
 sub MY::postamble { 
'
 $(MYEXTLIB): mylib/Makefile 
 cd mylib && $(MAKE) $(PASSTHRU) 
'; 
 }

在 MY::postamble 中进入 mylib 子目录并运行其下的 Makefile 进行编译，以生成静态库 libmylib.a。

注意： ‘ cd ’ 前面应该是 ‘ Tab ’ 而不是空格，否则 Make 会报 “missing separator” 错误并终止编译。

修改 MANIFEST 文件使其能够正确包含该扩展接口的所有内容。

清单 23 . 修改 MANIFEST 文件
mylib/Makefile.PL mylib/test1.c mylib/test2.c mylib/test.h
修改 Mytest.xs 文件并添加函数定义。

清单 24 . 修改 #include test.h
#include "mylib/test.h"
修改路径为 mylib/test.h 并将尖括号 <> 改为双引号””，以使编译程序能正确找到 mylib 子目录下面的 test.h 头文件。

清单 25 . 添加 add() 和 max() 函数定义
double add(a,b) int a long b int max(a,b) int a int b
提供 Perl 与 C 之间的接口函数，使得 Perl 代码通过 Mytest.xs 中的接口函数可以直接调用相应的 C 函数 add(a,b) 和 max(a,b) 函数。
在 Mytest 目录下运行 ”perl Makefile.PL” 生成 Makefile。

清单 26 . 运行 perl Makefile.PL
% perl Makefile.PL Checking if your kit is complete... Looks good Writing Makefile for Mytest::mylib Writing Makefile for Mytest %
编译器根据 Makefile.PL 自动生成相应的 Makefile 和 mylib 子目录下的 Makefile。

运行 ”make” 生成需要的库文件。

清单 27 . 运行 make

				  
 % make 
 gcc  -c <compile_flag>   test1.c 
 gcc  -c   <compile_flag> test2.c 
 ar cr libmylib.a test1.o test2.o 
 : libmylib.a 
 perl xsubpp -typemap typemap  Mytest.xs > Mytest.xsc && mv Mytest.xsc Mytest.c 
 Please specify prototyping behavior for Mytest.xs (see perlxs manual) 
 gcc  -c  <compile_flag>   Mytest.c 
 rm -f blib/arch/auto/Mytest/Mytest.so 
 gcc <compile_flag> Mytest.o -o blib/arch/auto/Mytest/Mytest.so mylib/libmylib.a 

 chmod 755 blib/arch/auto/Mytest/Mytest.so 
 cp Mytest.bs blib/arch/auto/Mytest/Mytest.bs 
 chmod 644 blib/arch/auto/Mytest/Mytest.bs 
 Manifying blib/man3/Mytest.3pm 
 %

修改 Mytest.t 文件，添加测试代码

清单 28 . 修改 Mytest.t
is( &Mytest::add(1,2),6 ); is( &Mytest::add(3,1),7 ); is( &Mytest::max(1,2 ); is( &Mytest::max(3,3 );
测试代码以不同的参数调用 Mytest::add() 和 Mytest::max() 并同预期结果比较，以确认相应的 C 函数 add() 和 max() 被正确调用。

运行命令 ”make test”，确保所有测试结果正确。

清单 29 . 运行 make test

				  
 % make test 
 PERL_DL_NONLAZY=1 /usr/bin/perl "-MExtUtils::Command::MM" "-e" "test_harness 
 (0,'blib/lib','blib/arch')" *.t 
 Mytest....ok                                                               
 All tests successful. 
 Files=1,Tests=4,0 wallclock secs ( 0.03 cusr +  0.01 csys =  0.04 CPU) 
 %

从结果可以看到测试全部通过，说明相应 C 函数被调用并计算得到了正确的结果。

运行命令 ”make install”，将生成的库文件安装到系统目录中。
至此，我们就能在自己的 Perl 代码中直接调用 test1.c 和 test2.c 里面定义的函数 add() 和 max() 了。

清单 30 .Perl 代码调用

				  
 use Mytest; 
 my $sum = &Mytest::add(1,2); 
 my $max = &Mytest::max(2,3); 
 print “Sum of 1 add 2 is: $sum/n”; 
 print “Max of 2 and 3 is: $max/n”;

结束语

本文介绍了如何在 Unix 上编写和编译 Perl 对 C 的扩展接口 XS，使得 Perl 可以调用 C 代码（或者 C 库）中定义的函数。读者通过本文介绍的详细步骤，可以自行编写 XS 扩展接口，并编译成静态或动态库文件，供 Perl 代码调用。

Perl 对 C 的扩展接口

相关推荐