Module...:XSUtil(3pm)

💖 Module::Install::XSUtil — the manual page, but make it a group chat 💖

okay bestie, so this is the Module::Install::XSUtil(3pm) page from the User Contributed Perl Documentation section, and it's literally your little toolkit for setting up distros that include or depend on XS modules. XS!! compiled!! spicy!! 🔥

---

✨ NAME ✨

Module::Install::XSUtil — literally just utility functions for XS modules. that's the whole name. it's giving helpful. 🎀

🌸 VERSION 🌸

this doc describes Module::Install::XSUtil version 0.45. yes we're keeping the numbers, no we're not rounding. periodt. 💅

🦋 SYNOPSIS 🦋

so this is what it looks like in your Makefile.PL:

# in Makefile.PL
use inc::Module::Install;

# Enables C compiler warnings
cc_warnings;

# Uses ppport.h
# No need to include it. It's created here.
use_ppport 3.19;

# Sets C pre-processor macros.
cc_define q{-DUSE_SOME_FEATURE=42};

# Sets paths for header files
cc_include_paths 'include'; # all the header files are in include/

# Sets paths for source files
cc_src_paths 'src'; # all the XS and C source files are in src/

# Installs header files
install_headers; # all the header files in @cc_include_paths

look at her go. main character Makefile.PL energy fr fr. ✨

🌈 DESCRIPTION 🌈

Module::Install::XSUtil hands you a whole set of utilities to setup distributions which include or depend on XS module. that's the job. that's the vibe.

wanna see it out in the wild? check XS::MRO::Compat and Method::Cumulative for example. iykyk 👑

---

💜 FUNCTIONS 💜

cc_available

returns true if a C compiler is available. and listen — YOU DO NOT NEED TO CALL THIS FUNCTION YOURSELF: it gets called for you when this module is initialized, and your Makefile.PL process will exit with 0 status. so it's lowkey doing its own thing. only explicitly call it if you need to do some esoteric handling when no compiler is available (for example, when you have a pure perl alternative). fancy. 🤓

c99_available

returns true if a C compiler is available and it supports C99 features. two for one. slay. 💅

want_xs ?$default

returns true if the user asked for the XS version or pure perl version of the module.

• will return true if --xs is explicitly specified as the argument to Makefile.PL
• and false if --pp is specified
• if neither is explicitly specified, it will return the value specified by $default
• and if you do not specify the value of $default, then it will be true

letting the user choose? that's literally democracy bestie 🫶

use_ppport ?$version

creates ppport.h using Devel::PPPort::WriteFile(). so you don't have to write it yourself, she does it for you.

this command also calls configure_requires 'Devel::PPPort' => $version and adds -DUSE_PPPORT to MakeMaker's DEFINE. multi-tasking icon behavior. 🎀

use_xshelper ?-clean|-realclean

creates sxshelper.h, which is a helper header file to include EXTERN.h, perl.h, XSUB.h and ppport.h, and defines some portability stuff which are not supported by ppport.h.

the optional argument -clean and -realclean set clean_files or realclean_files to the generated file xshelper.h respectably. (that's a typo in the source, we do NOT fix it, we respect the original 💖)

this command includes use_ppport. so it's a package deal, no takebacks.

cc_warnings

enables C compiler warnings. let the compiler scream at you, it's good for you, it's like a vibe check for your code. 🔥

cc_define @macros

sets cpp macros as compiler options.

cc_src_paths @source_paths

sets source file directories which include *.xs or *.c. all your little source files, cozy in one folder. 🌸

cc_include_paths @include_paths

sets include paths for a C compiler.

cc_inc_paths @include_paths;

okay so this one USED to be an alias to cc_include_paths, but from 0.42, this is Module::Install::Compiler::cc_inc_paths, which replaces the EUMM's INC parameter.

bestie. don't use this function. use cc_include_paths instead. it's deprecated-adjacent and we're moving on. 🚫

cc_libs @libs

sets MakeMaker's LIBS. if a name starts -, it will be interpreted as is. otherwise prefixed -l. cute little rule, very consistent.

e.g.:

cc_libs -lfoo;
cc_libs  'foo'; # ditto.
cc_libs qw(-L/path/to/libs foo bar); # with library paths

see how -lfoo and 'foo' are the same thing? the way that she normalizes everything 😭 beautiful

cc_assert_lib %args

checks if the given C library is installed via Devel::CheckLib. takes exactly what Devel::CheckLib takes. note that you must pass the path names explicitly. no guessing, no assuming, explicit only. 👀

requires_c99

tells the build system to use C99 features.

requires_cplusplus

tells the build system to use C++ language. yes, plus plus. extra plus. 💅

install_headers ?@header_files

declares providing header files, extracts functions from these header files, and adds these functions to MakeMaker's FUNCLIST.

if @header_files are omitted, all the header files in include paths will be installed. so it just grabs everything. generous queen. 👑

cc_append_to_inc @include_paths

low level API. that's it, that's the description. she's mysterious. 🙈

cc_append_to_libs @libraries

low level API.

cc_append_to_ccflags @ccflags

low level API.

cc_append_to_funclist @funclist

low level API.

---

🎀 OPTIONS 🎀

under the control of this module, Makefile.PL accepts -g option, which sets MakeMaker's OPTIMIE -g (or something like). it will disable optimization and enable some debugging features.

yes OPTIMIE is spelled like that in the original. not me. it stays. ✨

---

🧚 DEPENDENCIES 🧚

Perl 5.5.3 or later. old school but iconic.

---

⭐ NOTE ⭐

in Makefile.PL, you might want to use author_requires, which is provided by Module::Install::AuthorReauires, in order to tell co-developers that they need to install this plugin.

author_requires 'Module::Install::XSUtil';

(AuthorReauires — again, typo, not mine, preserving the artifact 🫶)

---

💀 BUGS 💀

No bugs have been reported. zero. none. flawless. well.

please report any bugs or feature requests to the author.

---

🌸 ACKNOWLEDGEMENT 🌸

thanks to Taro Nishino for the test reports. 🫶

Tanks to lestrrat for the suggestions and patches.

"Tanks" 💖 we love it here. keep it.

---

👑 AUTHOR 👑

Goro Fuji (gfx) <gfuji(at)cpan.org>.

---

🌈 SEE ALSO 🌈

• ExtUtils::Depends.
• Module::Install.
• Module::Install::CheckLib.
• Devel::CheckLib.
• ExtUtils::MakeMaker.

all the cousins. the whole family tree. 🦋

---

💅 LICENSE AND COPYRIGHT 💅

Copyright (c) 2009-2010, Goro Fuji (gfx). All rights reserved.

This library 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, no cap. this manual page was rendered from perl v5.36.0 and dated 2022-10-14 — go off, you read all of it, that's main character behavior fr fr 💖✨🎀