Module::Install::XSUtil(3pm)

1Module::Install::XSUtilU(s3e)r Contributed Perl DocumentaMtoidounle::Install::XSUtil(3)
2
3
4

NAME

6       Module::Install::XSUtil - Utility functions for XS modules
7

VERSION

9       This document describes Module::Install::XSUtil version 0.45.
10

SYNOPSIS

12           # in Makefile.PL
13           use inc::Module::Install;
14
15           # Enables C compiler warnings
16           cc_warnings;
17
18           # Uses ppport.h
19           # No need to include it. It's created here.
20           use_ppport 3.19;
21
22
23           # Sets C pre-processor macros.
24           cc_define q{-DUSE_SOME_FEATURE=42};
25
26           # Sets paths for header files
27           cc_include_paths 'include'; # all the header files are in include/
28
29           # Sets paths for source files
30           cc_src_paths 'src'; # all the XS and C source files are in src/
31
32           # Installs header files
33           install_headers; # all the header files in @cc_include_paths
34

DESCRIPTION

36       Module::Install::XSUtil provides a set of utilities to setup
37       distributions which include or depend on XS module.
38
39       See XS::MRO::Compat and Method::Cumulative for example.
40

FUNCTIONS

42   cc_available
43       Returns true if a C compiler is available. YOU DO NOT NEED TO CALL THIS
44       FUNCTION YOURSELF: it will be called for you when this module is
45       initialized, and your Makefile.PL process will exit with 0 status.
46       Only explicitly call if you need to do some esoteric handling when no
47       compiler is available (for example, when you have a pure perl
48       alternative)
49
50   c99_available
51       Returns true if a C compiler is available and it supports C99 features.
52
53   want_xs ?$default
54       Returns true if the user asked for the XS version or pure perl version
55       of the module.
56
57       Will return true if "--xs" is explicitly specified as the argument to
58       Makefile.PL, and false if "--pp" is specified. If neither is explicitly
59       specified, will return the value specified by $default. If you do not
60       specify the value of $default, then it will be true.
61
62   use_ppport ?$version
63       Creates ppport.h using Devel::PPPort::WriteFile().
64
65       This command calls "configure_requires 'Devel::PPPort' => $version" and
66       adds "-DUSE_PPPORT" to "MakeMaker"'s "DEFINE".
67
68   use_xshelper ?-clean|-realclean
69       Create sxshelper.h, which is a helper header file to include EXTERN.h,
70       perl.h, XSUB.h and ppport.h, and defines some portability stuff which
71       are not supported by ppport.h.
72
73       Optional argument "-clean" and "-realclean" set "clean_files" or
74       "realclean_files" to the generated file xshelper.h respectably.
75
76       This command includes "use_ppport".
77
78   cc_warnings
79       Enables C compiler warnings.
80
81   cc_define @macros
82       Sets "cpp" macros as compiler options.
83
84   cc_src_paths @source_paths
85       Sets source file directories which include *.xs or *.c.
86
87   cc_include_paths @include_paths
88       Sets include paths for a C compiler.
89
90   cc_inc_paths @include_paths;
91       This was an alias to "cc_include_paths", but from 0.42, this is
92       "Module::Install::Compiler::cc_inc_paths", which replaces the EUMM's
93       "INC" parameter.
94
95       Don't use this function. Use "cc_include_paths" instead.
96
97   cc_libs @libs
98       Sets "MakeMaker"'s "LIBS". If a name starts "-", it will be interpreted
99       as is.  Otherwise prefixed "-l".
100
101       e.g.:
102
103           cc_libs -lfoo;
104           cc_libs  'foo'; # ditto.
105           cc_libs qw(-L/path/to/libs foo bar); # with library paths
106
107   cc_assert_lib %args
108       Checks if the given C library is installed via Devel::CheckLib.  Takes
109       exactly what Devel::CheckLib takes. Note that you must pass the path
110       names explicitly.
111
112   requires_c99
113       Tells the build system to use C99 features.
114
115   requires_cplusplus
116       Tells the build system to use C++ language.
117
118   install_headers ?@header_files
119       Declares providing header files, extracts functions from these header
120       files, and adds these functions to "MakeMaker"'s "FUNCLIST".
121
122       If @header_files are omitted, all the header files in include paths
123       will be installed.
124
125   cc_append_to_inc @include_paths
126       Low level API.
127
128   cc_append_to_libs @libraries
129       Low level API.
130
131   cc_append_to_ccflags @ccflags
132       Low level API.
133
134   cc_append_to_funclist @funclist
135       Low level API.
136

OPTIONS

138       Under the control of this module, Makefile.PL accepts "-g" option,
139       which sets "MakeMaker"'s "OPTIMIE" "-g" (or something like). It will
140       disable optimization and enable some debugging features.
141

DEPENDENCIES

143       Perl 5.5.3 or later.
144

NOTE

146       In Makefile.PL, you might want to use "author_requires", which is
147       provided by "Module::Install::AuthorReauires", in order to tell co-
148       developers that they need to install this plugin.
149
150           author_requires 'Module::Install::XSUtil';
151

BUGS

153       No bugs have been reported.
154
155       Please report any bugs or feature requests to the author.
156

ACKNOWLEDGEMENT

158       Thanks to Taro Nishino for the test reports.
159
160       Tanks to lestrrat for the suggestions and patches.
161

AUTHOR

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

LICENSE AND COPYRIGHT

177       Copyright (c) 2009-2010, Goro Fuji (gfx). All rights reserved.
178
179       This library is free software; you can redistribute it and/or modify it
180       under the same terms as Perl itself.
181
182
183
184perl v5.38.0                      2023-07-20        Module::Install::XSUtil(3)