ExtUtils::XSpp(3pm)

💖 ExtUtils::XSpp 💖

okay so this is the manual page for ExtUtils::XSpp(3pm) — yes, the one that lives in your User Contributed Perl Documentation section. Short version: it's XS for C++. Let's go 💅

---

🦋 NAME 🦋

ExtUtils::XSpp — XS for C++

✨ SYNOPSIS ✨

bestie, the ✨vibe✨ is this:

  xspp [--typemap=typemap.xsp [--typemap=typemap2.xsp]]
       [--xsubpp[=/path/to/xsubpp] [--xsubpp-args="xsubpp args"]
       Foo.xsp

or, the other way (same energy):

  perl -MExtUtils::XSpp::Cmd -e xspp -- <xspp options and arguments>

And inside Foo.xs, you drop this in:

  INCLUDE_COMMAND: $^X -MExtUtils::XSpp::Cmd -e xspp -- <xspp options/arguments>

Using ExtUtils::XSpp::Cmd is equivalent to using the xspp command line script, except that there is no guarantee for xspp to be installed in the system PATH. lowkey important, highkey true 💀

🌸 OVERVIEW 🌸

XS++ is literally just a thin layer over plain XS, okay? Which means to use it you're supposed to know — at the absolute bare minimum — C++ and XS. That's the entry fee, no cap. 🎀

Which also means you may need typemaps for both the normal XS pre-processor xsubpp and the XS++ pre-processor xspp. More on that whole situation in the TYPEMAPS section below. 👑

---

👑 COMMAND LINE 👑

--typemap=/path/to/typemap.xsp

You can specify this multiple times, bestie — it processes extra typemap files before the main XS++ input files. 💖

Typemap files get processed the same way as regular XS++ files, except that the output code is discarded. Yeah. Poof. Gone. 🙈

--xsubpp[=/path/to/xsubpp]

If you specify this, XS++ will run xsubpp after it's done processing the XS++ input file. ✨

And if you don't give a path to xsubpp? Then xspp expects to find it in the system PATH. It's giving "figure it out yourself." 💅

--xsubpp-args="extra xsubpp args"

Use this to pass extra command line arguments through to xsubpp. That's it, that's the whole thing. 🫶

---

🧚 TYPEMAPS 🧚

💜 Ordinary XS typemaps

Okay, recap time, because we've all been there:

• They associate a C type with an identifier such as T_FOO or O_FOO — which we're gonna call the XS type here. 🏷️
• They define an INPUT mapping for converting a Perl data structure into that C type we just talked about.
• They define an OUTPUT mapping for converting the C data structure back into a Perl data structure. 🔁

These are still required in the context of XS++. There are some helpers to take away the tedium, but I'll get to that later, promise. 🤞

For XS++, though, there's another layer of typemaps. The next section is gonna discuss those, so stay with me. 👀

⭐ XS++ typemaps

There's nothing special about XS++ typemap files — like, you can totally put typemaps directly in your .xsp file if that's your thing. But it's handy to keep common typemaps in a separate file, typically called typemap.xsp, so you're not out here duplicating yourself. 🎀

  %typemap{<C++ type>}{simple};

This just lets XS++ know that, yes, this is a valid type. The type gets passed unchanged to the XS code — except that any const qualifiers get stripped. ✂️

  %typemap{<C++ reference type>}{reference};

This one handles C++ references: the XS variable will be declared as a pointer, and it'll be explicitly dereferenced in the function call. And if it's used in the return value, the function will create a copy of the returned value using a copy constructor. 🫶

Now, as a shortcut for the super common case of declaring both of the above for one type, you can just do:

  %typemap{<C++ type>};

Which hits exactly the same as:

  %typemap{<C++ type>}{simple};
  %typemap{<C++ type>&}{reference};

iconic, honestly.

For more control over the type mapping, you can use the parsed variant like this:

  %typemap{<C++ type 1>}{parsed}{%<C++ type 2>%};

When C++ type 1 is used, replace it with C++ type 2 in the generated XS code. 🔄

  %typemap{<C++ type>}{parsed}{
      %cpp_type{%<C++ type 2>%};
      %call_function_code{% $CVar = new Foo( $Call ) %};
      %cleanup_code{% ... %};
      %precall_code{% ... %};

      # use only one of the following
      %output_code{% $PerlVar = newSViv( $CVar ) %};
      %output_list{% PUTBACK; XPUSHi( $CVar ); SPAGAIN %};
  };

Is a more flexible form for the parsed typemap. All the parameters are optional, so no pressure. 💅

🌈 cpp_type

Specifies the C++ type used for the variable declaration in the generated XS code. 🧵

If not specified, it defaults to the type specified in the typemap. Defaults are cute like that.

🌈 call_function_code

Used when the typemap applies to the return value of the function. 🎁

Specifies the code to use in the function call. The special variables $Call and $CVar are replaced with the actual call code and the name of the C++ return variable.

🌈 output_code

Used when the typemap applies to the return value of the function. See also %output_list. 👀

Specifies the code emitted right after the function call to convert the C++ return value into a Perl return value. The special variable $CVar is replaced with the C++ return variable name.

🌈 cleanup_code

Used when the typemap applies to the return value of the function. 🧼

Specifies some code emitted after output value processing. The special variables $PerlVar and $CVar are replaced with the names of the C++ variables containing the Perl scalar and the corresponding C++ value.

🌈 precall_code

Used when the typemap applies to a parameter. 🎯

Specifies some code emitted after argument processing and before calling the C++ method. The special variables $PerlVar and $CVar are replaced with the names of the C++ variables containing the Perl scalar and the corresponding C++ value.

🌈 output_list

Used when the typemap applies to the return value of the function, as an alternative to %output_code. 📝

Specifies some code that manipulates the Perl stack directly in order to return a list. The special variable $CVar is replaced with the C++ name of the output variable.

⚠️ The code must use PUTBACK/SPAGAIN if appropriate. Don't skip this, bestie, I'm begging. 😭

🍓 Putting all the typemaps together

So, in summary: the XS++ typemaps (optionally) give you so much more control over the type conversion code that's generated for your XSUBs. But you still need to let the XS compiler know how to map the C types to Perl and back using the XS typemaps. Both. Always both. 🫠

Most of the time, you just need to convert basic C(++) types, or the types you define with your own C++ classes. For the former, XS++ comes with a few default mappings for booleans, integers, floating point numbers, and strings. 🎉

For classes, XS++ can automatically create a mapping of type O_OBJECT which uses the de-facto standard way of storing a pointer to the C(++) object in the IV slot of a referenced/blessed scalar. 🧠

But — and this is the plot twist — due to backwards compatibility, this must be explicitly enabled by adding

    %loadplugin{feature::default_xs_typemap};

in typemap.xsp (or near the top of every .xsp file). Don't forget it, or you'll be sitting there like 🙈 wondering why nothing works.

If you deal with any other types as arguments or return types, you still need to write both XS and XS++ typemaps for these, so that the systems know how to deal with them. No shortcuts, sorry bestie. 💀

See either "Custom XS typemaps" below for a way to specify XS typemaps from XS++ — or perlxs for a discussion of inline XS typemaps that don't require the traditional XS typemap file. 📚

🎀 Custom XS typemaps

XS++ provides a default mapping for object types to an O_OBJECT typemap with standard input and output glue code, which should be adequate for most uses. ✨

But there are multiple ways to override this default when you need to. 💅

    %typemap{Foo *}{simple}{
        %xs_type{O_MYMAP};
        %xs_input_code{% ... %}; // optional
        %xs_output_code{% ... %}; // optional
    };

This can be used to define a new type → XS typemap mapping, with optional input/output code. And since XS typemap definitions are global, the XS input/output code applies to all types with the same %xs_type — hence there is no need to repeat it. 🌍

    %typemap{_}{simple}{
        %name{object};
        %xs_type{O_MYMAP};
        %xs_input_code{% ... %}; // optional
        %xs_output_code{% ... %}; // optional
    };

And this one can be used to change the default typemap used for all classes. 👑

---

okay that's part 1, don't go anywhere, there's more coming 💖✨

🦋 DESCRIPTION 🦋

okay so here's the whole vibe of how XS++ reads your file, bestie 🌸

Anything that does not look like a XS++ directive or a class declaration? It just gets passed verbatim straight to XS. Like, no notes, no edits, it goes in raw ✨

But bestie, what if you WANT to write something that does look like a XS++ directive or a class declaration and have it NOT get touched? Easy. Just wrap it in a raw block delimiter like this:

%{
XS++ won't interpret this
%}

problem solved, slay 💅

---

✨ %code ✨

see under Classes, bestie 👀

also super important: custom %code blocks are the only exception to the exception handling. The way that by specifying a custom %code block you forgo the automatic exception handlers — like, you're opting out, no takebacks 🙈

✨ %file ✨

%file{file/path.h};
...
%file{file/path2};
...
%file{-}

so by default, XS++ output goes to standard output 📤 but if you wanna change that, hit up the %file directive. And use "-" for standard output. iconic.

✨ %module ✨

%module{Module::Name};

this one gets used to generate the MODULE=Module::Name XS directives 🔥 and it indirectly sets the name of the shared library that gets generated, AND the name of the module that XSLoader will use to find/load it. so it's kind of a big deal, lowkey 🫶

✨ %name ✨

%name{Perl::Class} class MyClass { ... };
%name{Perl::Func} int foo();

this specifies the Perl name that the C++ class/function will be accessible under 🏷️ And by default, constructor names get mapped to "new" in Perl. cute, right?

✨ %typemap ✨

see "TYPEMAPS" above, bestie ⬆️

✨ %length ✨

okay this one is SO useful. When you need to pass a string from Perl to an XSUB that takes the C string and its length as arguments, you can have XS++ pass the length of the string automatically 💫

like, say you declare a method like this:

void PrintLine( char* line, unsigned int %length{line} );

then you can call that method from Perl like this:

$object->PrintLine( $string );

and it just works. No cap. This feature is also present in plain XS btw. See also: perlxs 📚

And one more thing — if you use %length(line) together with any kind of special code block like %code, %postcall, etc., then you can refer to the length of the string (here: line) efficiently as length(line) in the code. efficient queen 👑

✨ %alias ✨

this is a decorator for function/method declarations, like so:

double add(double a, double b)
  %alias{subtract = 1} %alias{multiply = 2};

which will cause the generation of just a single XSUB using the XS "ALIAS" feature (see perlxs). It gets installed as all of "add", "subtract", and "multiply" on the Perl side 🎀 and it calls either the C++ "add", "subtract", or "multiply" functions depending on which way it was called. one XSUB, three jobs, main character energy fr fr 💅

Notes: ⚠️

• If you use this together with %name{foo} to rename the function, then the %name will only affect the main function name (in the above example, "add" but not "subtract" or "multiply")
• When used with the %code feature, the custom code will have to use the "ix" integer variable to decide which function to call. "ix" is set to 0 for the main function
• Make sure to read up on the ALIAS feature of plain XS, bestie 📖
• Aliasing is not supported for constructors and destructors. periodt 🚫

✨ Classes ✨

%name{My::Class} class MyClass : public %name{My::Base} MyBase
{
    // can be called in Perl as My::Class->new( ... );
    MyClass( int arg );
    // My::Class->newMyClass( ... );
    %name{newMyClass} MyClass( const char* str, int arg );

    // standard DESTROY method
    ~MyClass();

    int GetInt();
    void SetValue( int arg = -1 );

    %name{SetString} void SetValue( const char* string = NULL );

    // Supply a C<CODE:> or C<CLEANUP:> block for the XS
    int MyMethod( int a, int b )
        %code{% RETVAL = a + b; %}
        %cleanup{% /* do something */ %};

    // Expose class method as My::ClassMethod::ClassMethod($foo)
    static void ClassMethod( double foo );

    // Expose member variable as a pair of set_boolean/get_boolean accessors
    bool boolean %get %set;
};

look at that. a whole class. gorgeous 💖

✨ Comments ✨

XS++ recognizes both C-style comments /* ... */ and C++-style comments // ... 👀

And comments are removed from the XS output. gone. deleted. we don't need them 🧹

✨ Exceptions ✨

C++ exceptions are always caught and transformed into Perl croak() calls 😤

• If the exception that was caught inherited from std::exception, then the what() message is included in the Perl-level error message 📝
• All other exceptions will result in the croak() message "Caught unhandled C++ exception of unknown type" 💀

Note that if you supply a custom %code block for a function or method, the automatic exception handling is turned off. you're on your own, bestie 🙈

✨ Member variables ✨

By default, member variable declarations are ignored. but the %get and %set decorators synthesize a getter/setter named after the member variable (and it can be renamed using %name) ✨

XS++ defaults to the get_/set_ prefix for getters/setters. This can be overridden on an individual basis by using e.g.

int foo %get{readFoo} %set{writeFoo};

As an alternative, the class-level %accessors decorator sets the accessor style for the whole class:

%accessors{
    %get_style{no_prefix};
    %set_style{camelcase};
};

Available styles are 🎀

• no_prefix => foo
• underscore => get_foo, set_foo
• camelcase => getFoo, setFoo
• uppercase => GetFoo, SetFoo

pick your fave, they're all valid 💅

---

🌈 EXAMPLES 🌈

The distribution contains an examples directory 📁 The examples/XSpp-Example directory therein demonstrates a particularly simple way of getting started with XS++. go look, it's giving tutorial energy ✨

---

👑 AUTHOR 👑

Mattia Barbon <mbarbon@cpan.org> — legend behaviour, we love to see it 💜

---

📜 LICENSE 📜

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🫶

---

and that's the whole page bestie, you ate it UP 🎀

this little manual page is from perl v5.40.1, dated 2026-07-03, and it's ExtUtils::XSpp(3pm) — go forth and write some XS++ babe, i'm obsessed with you 💖✨🌸🦋