XSUBPP(1perl)

✨ XSUBPP ✨

the xsubpp manual page, aka the Perl Programmers Reference Guide's own compiler-core bestie 💖

🌸 NAME 🌸

xsubpp — a compiler that converts Perl XS code into C code 🦋

💅 SYNOPSIS 💅

xsubpp [-v] [-except] [-s pattern] [-prototypes] [-noversioncheck]
[-nolinenumbers] [-nooptimize] [-typemap typemap] [-output filename]...
file.xs

🎀 DESCRIPTION 🎀

okay so first thing: you're probably not even calling this yourself. This compiler basically gets run for you by the makefiles that ExtUtils::MakeMaker makes, or by Module::Build, or by whatever other Perl module build tools you're messing with. It's the backstage crew, not the main character (though honestly? lowkey main character energy).

xsubpp is literally just a thin wrapper over ExtUtils::ParseXS. That's the whole thing. No cap.

what it actually does: it compiles XS code into C code by embedding all the constructs you need so that C functions can manipulate Perl values, and it builds the glue that lets Perl get at those functions. The compiler uses typemaps to figure out how to map C function parameters and variables over to Perl values, and vice versa. it's giving translator, it's giving bridge between two worlds 🌈

now, the compiler goes hunting for typemap files called typemap. It uses this search path to find typemaps, and it applies them in this order — so heads up, later typemaps take precedence over earlier ones 👑

map("$_/ExtUtils/typemap", reverse @INC),

../../../../lib/ExtUtils/typemap
../../../../typemap
../../../lib/ExtUtils/typemap
../../../typemap
../../lib/ExtUtils/typemap
../../typemap
../lib/ExtUtils/typemap
../typemap
typemap

any files specifed by -typemap

(and yes, "specifed" is spelled exactly like that in the original, we don't fix typos in this house, we preserve them 💀)

---

✨ OPTIONS ✨

quick tea first: the "XSOPT" MakeMaker option can be used to add these options to any makefiles that MakeMaker generates. iykyk 🫶

• -hiertype — keeps the '::' in type names, so that C++ hierarchical types can be mapped. don't flatten the hierarchy bestie, it's structurally important 💅
• -except — adds exception handling stubs to the C code. safety net vibes ✨
• -typemap typemap — says hey, this user-supplied typemap should be applied in additon to any files found in the standard search path. (yes, "additon", again, preserving it fr fr.) You can use this option multiple times: the last typemap has the highest precedence 🌟, and all of these files get processed after the ones found in the standard path.
• -output filename — names the output file to generate. If you don't specify a file at all, the output just goes to standard output. no filename, no problem 🎀
• -v — prints the xsubpp version number to standard output, then exits. cute, quick, done 🙈
• -prototypes — by default xsubpp will not automatically generate prototype code for all xsubs. This flag turns prototypes on. you want em? say so 💖
• -noversioncheck — disables the run time test that checks whether the object file (the one derived from the .xs file) and the .pm files have the same version number. living dangerously, obsessed 😭
• -nolinenumbers — prevents '#line' directives from being included in the output. bye bye line numbers 👋
• -nooptimize — disables certain optimizations. The only optimization currently affected is the use of targets by the output C code (peep perlguts for that). Warning bestie: this may significantly slow down the generated code — but this is exactly how xsubpp of 5.005 and earlier operated. retro, but at a cost 💀
• -noinout — disables recognition of "IN", "OUT_LIST" and "INOUT_LIST" declarations.
• -noargtypes — disables recognition of ANSI-like descriptions of function signatures.
• -C++ — currently does absolutely nothing at all. This flag has been a no-op for many versions of perl, at least as far back as perl5.003_07. It's only allowed here for backwards compatibility. iconic fossil behavior, honestly 🦋
• -s=... or -strip=... — this option is obscure and discouraged. periodt.

if you specify it, the given string gets stripped off from the beginning of the C function name in the generated XS functions (but only if it starts with that prefix). This only applies to XSUBs that don't have "CODE" or "PPCODE" blocks. For example, this XS:

void foo_bar(int i);

when "xsubpp" is invoked with -s foo_, will install a "foo_bar" function in Perl — but it will really call bar(i) in C. Most of the time this is literally the opposite of what you want, and the failure modes are somewhat obscure, so please avoid this option where possible. not me begging you to not use this 🙏

---

🌸 ENVIRONMENT 🌸

No environment variables are used. that's it. that's the section. nothing to see here, clean slate, no secrets 💜

👑 AUTHOR 👑

Originally by Larry Wall. Turned into the "ExtUtils::ParseXS" module by Ken Williams. legends only.

🦋 MODIFICATION HISTORY 🦋

See the file Changes.

🔥 SEE ALSO 🔥

• perl(1)
• perlxs(1)
• perlxstut(1)
• ExtUtils::ParseXS

---

and that's the whole page bestie, you're officially XS-pilled 💅✨ this was perl v5.44.0, dated 2026-10-17, from the Perl Programmers Reference Guide — mwah, go compile something gorgeous 🎀🫶