Editing XS (Perl)

'''XS''' is a [[Perl]] [[foreign function interface]] through which a program can call a [[C (programming language)|C]] or [[C++]] [[subroutine]]. XS or '''xsub''' is an [[abbreviation]] of "eXtendable Subroutine".

XS also refers to a [[glue language]] for specifying calling interfaces supporting such interfaces (see below).

==Background==

Subroutine libraries in Perl are called ''modules'', and modules that contain xsubs are called ''XS modules''. Perl provides a framework for developing, packaging, distributing, and installing modules.

It may be desirable for a Perl program to invoke a C subroutine in order to handle very [[CPU]] or [[random-access memory|memory]] intensive tasks, to interface with [[computer hardware|hardware]] or low-level system facilities, or to make use of existing C subroutine libraries.

===Perl interpreter===
{{main|calling convention}}

The [[interpreter (computing)|Perl interpreter]] is a C program, so in principle there is no obstacle to calling from Perl to C. However, the XS interface is complex{{why|date=January 2017}} and highly technical, and using it requires some understanding of the interpreter. The earliest reference on the subject was the [https://web.archive.org/web/20150219101254/http://perldoc.perl.org/perlguts.html perlguts] [[Plain Old Documentation|POD]].

==Wrappers==

It is possible to write XS modules that [[Wrapper function|wrap]] [[C++]] code. Doing so is mostly a matter of configuring the module [[Software build|build]] system.<ref>{{cite web |url=http://www.johnkeiser.com/perl-xs-c++.html |title=Gluing C++ And Perl Together |date=August 27, 2001 |publisher=johnkeiser.com |url-status=dead |access-date=May 5, 2005 |archive-date=December 11, 2001 |archive-url=https://web.archive.org/web/20011211212254/http://www.johnkeiser.com/perl-xs-c++.html }}</ref>

==Example code==

The following shows an XS module that exposes a function <code>concat()</code> to concatenate two strings (i.e., the equivalent of Perl’s <code>.</code> operator).
<syntaxhighlight lang="c">
#define PERL_NO_GET_CONTEXT
#include "EXTERN.h"
#include "perl.h"
#include "XSUB.h"

SV* _do_sv_catsv (pTHX_ SV* one_sv, SV* two_sv ) {
    SV* one_copy = newSVsv(one_sv);
    sv_catsv(one_copy, two_sv);
    return one_copy;
}
</syntaxhighlight>

<syntaxhighlight lang="c">
MODULE = Demo::XSModule      PACKAGE = Demo::XSModule

SV*
concat (SV* one_sv, SV* two_sv)
    CODE:
        SV* to_return = _do_sv_catsv( aTHX_ one_sv, two_sv );
        RETVAL = to_return;

    OUTPUT:
        RETVAL
</syntaxhighlight>

The first four lines (<code>#define</code> and <code>#include</code> statements) are standard boilerplate.

After then follow any number of plain C functions that are callable locally.

The section that starts with <code>MODULE = Demo::XSModule</code> defines the Perl interface to this code using the actual XS macro language. Note that the C code under the <code>CODE:</code> section calls the <code>_do_sv_catsv()</code> pure-C function that was defined in the prior section.

Perl’s documentation explains the meaning and purpose of all of the “special” symbols (e.g., <code>aTHX_</code> and <code>RETVAL</code>) shown above.

To make this module available to Perl it must be compiled. Build tools like [https://perldoc.perl.org/ExtUtils::MakeMaker ExtUtils::MakeMaker] can do this automatically. (To build manually: the [https://perldoc.perl.org/xsubpp xsubpp] tool parses an XS module and outputs C source code; that source code is then compiled to a shared library and placed in a directory where Perl can find it.) Perl code then uses a module like [https://perldoc.perl.org/XSLoader XSLoader] to load the compiled XS module. At this point Perl can call <code>Demo::XSModule::concat('foo', 'bar')</code> and receive back a string <code>foobar</code>, as if <code>concat()</code> were itself written in Perl.

Note that, for building Perl interfaces to preexisting C libraries, the [[h2xs]]{{elucidate|date=January 2017}} can automate much of the creation of the XS file itself.

==Difficulties==

Creation and maintenance of XS modules requires expertise with C itself as well as Perl’s extensive C API. XS modules may only be installed if a [[C compiler]] and the [[header file]]s that the Perl interpreter was compiled against are available.  Also, new versions of Perl may break [[binary compatibility]] requiring XS modules to be recompiled.

==See also==

* [[SWIG]], an alternative to XS which also supports calling C and C++ functions from several other languages.
* [[Foreign_function_interface|FFI]], a mechanism which enables calling routines written in another language.

==References==
{{reflist}}
* Jenness, Tim & [[Simon Cozens|Cozens, Simon]] (2002). "Extending and Embedding Perl". Greenwich: Manning Publications Co. {{ISBN|1-930110-82-0}}

==External links==

* [https://web.archive.org/web/20120616065237/http://perldoc.perl.org/perlxs.html perlxs] Perl XS application programming interface
* [http://perldoc.perl.org/perlxstut.html perlxstut] Perl XS tutorial
* [https://web.archive.org/web/20150219101254/http://perldoc.perl.org/perlguts.html perlguts] Perl internal functions for those doing extensions
* [http://perldoc.perl.org/perlapi.html perlapi] Perl API listing (autogenerated)
* [https://web.archive.org/web/20041209010819/http://world.std.com/~swmcd/steven/perl/pm/xs/intro/index.html XS Mechanics] tutorial
* [https://web.archive.org/web/20011211212254/http://www.johnkeiser.com:80/perl-xs-c++.html Perl and C++] building XS modules for C++
* [https://github.com/xsawyerx/xs-fun xs-fun] XS is fun: a simple and easy tutorial on writing Perl XS

{{Perl}}

[[Category:Perl]]