1Module::Build::WithXSppU(s3eprm)Contributed Perl DocumenMtoadtuiloen::Build::WithXSpp(3pm)
2
3
4

NAME

6       Module::Build::WithXSpp - XS++ enhanced flavour of Module::Build
7

SYNOPSIS

9       In Build.PL:
10
11         use strict;
12         use warnings;
13         use 5.006001;
14
15         use Module::Build::WithXSpp;
16
17         my $build = Module::Build::WithXSpp->new(
18           # normal Module::Build arguments...
19           # optional: mix in some extra C typemaps:
20           extra_typemap_modules => {
21             'ExtUtils::Typemaps::ObjectMap' => '0',
22           },
23         );
24         $build->create_build_script;
25

DESCRIPTION

27       This subclass of Module::Build adds some tools and processes to make it
28       easier to use for wrapping C++ using XS++ (ExtUtils::XSpp).
29
30       There are a few minor differences from using "Module::Build" for an
31       ordinary XS module and a few conventions that you should be aware of as
32       an XS++ module author. They are documented in the "FEATURES AND
33       CONVENTIONS" section below. But if you can't be bothered to read all
34       that, you may choose skip it and blindly follow the advice in "JUMP
35       START FOR THE IMPATIENT".
36
37       An example of a full distribution based on this build tool can be found
38       in the ExtUtils::XSpp distribution under examples/XSpp-Example. Using
39       that example as the basis for your "Module::Build::WithXSpp"-based
40       distribution is probably a good idea.
41

FEATURES AND CONVENTIONS

43   XS files
44       By default, "Module::Build::WithXSpp" will automatically generate a
45       main XS file for your module which includes all XS++ files and does the
46       correct incantations to support C++.
47
48       If "Module::Build::WithXSpp" detects any XS files in your module, it
49       will skip the generation of this default file and assume that you wrote
50       a custom main XS file. If that is not what you want, and wish to simply
51       include plain XS code, then you should put the XS in a verbatim block
52       of an .xsp file. In case you need to use the plain-C part of an XS file
53       for "#include" directives and other code, then put your code into a
54       header file and "#include" it from an .xsp file:
55
56       In src/mystuff.h:
57
58         #include <something>
59         using namespace some::thing;
60
61       In xsp/MyClass.xsp
62
63         #include "mystuff.h"
64
65         %{
66           ... verbatim XS here ...
67         %}
68
69       Note that there is no guarantee about the order in which the XS++ files
70       are picked up.
71
72   Build directory
73       When building your XS++ based extension, a temporary build directory
74       buildtmp is created for the byproducts.  It is automatically cleaned up
75       by "./Build clean".
76
77   Source directories
78       A Perl module distribution typically has the module ".pm" files in its
79       lib subdirectory. In a "Module::Build::WithXSpp" based distribution,
80       there are two more such conventions about source directories:
81
82       If any C++ source files are present in the src directory, they will be
83       compiled to object files and linked automatically.
84
85       Any ".xs", ".xsp", and ".xspt" files in an xs or xsp subdirectory will
86       be automatically picked up and included by the build system.
87
88       For backwards compatibility, files of the above types are also
89       recognized in lib.
90
91   Typemaps
92       In XS++, there are two types of typemaps: The ordinary XS typemaps
93       which conventionally put in a file called typemap, and XS++ typemaps.
94
95       The ordinary XS typemaps will be found in the main directory, under
96       lib, and in the XS directories (xs and xsp). They are required to carry
97       the ".map" extension or to be called typemap.  You may use multiple
98       .map files if the entries do not collide. They will be merged at build
99       time into a complete typemap file in the temporary build directory.
100
101       The "extra_typemap_modules" option is the preferred way to do XS
102       typemapping.  It works like any other "Module::Build" argument that
103       declares dependencies except that it loads the listed modules at build
104       time and includes their typemaps into the build.
105
106       The XS++ typemaps are required to carry the ".xspt" extension or (for
107       backwards compatibility) to be called "typemap.xsp".
108
109   Detecting the C++ compiler
110       "Module::Build::WithXSpp" uses ExtUtils::CppGuess to detect a C++
111       compiler on your system that is compatible with the C compiler that was
112       used to compile your perl binary. It sets some additional
113       compiler/linker options.
114
115       This is known to work on GCC (Linux, MacOS, Windows, and ?) as well as
116       the MS VC toolchain. Patches to enable other compilers are very
117       welcome.
118
119   Automatic dependencies
120       "Module::Build::WithXSpp" automatically adds several dependencies (on
121       the currently running versions) to your distribution.  You can disable
122       this by setting "auto_configure_requires => 0" in Build.PL.
123
124       These are at configure time: "Module::Build", "Module::Build::WithXSpp"
125       itself, and "ExtUtils::CppGuess".  Additionally there will be a build-
126       time dependency on "ExtUtils::XSpp".
127
128       You do not have to set these dependencies yourself unless you need to
129       set the required versions manually.
130
131   Include files
132       Unfortunately, including the perl headers produces quite some pollution
133       and redefinition of common symbols. Therefore, it may be necessary to
134       include some of your headers before including the perl headers.
135       Specifically, this is the case for MSVC compilers and the standard
136       library headers.
137
138       Therefore, if you care about that platform in the least, you should use
139       the "early_includes" option when creating a "Module::Build::WithXSpp"
140       object to list headers to include before the perl headers. If such a
141       supplied header file starts with a double quote, "#include "..."" is
142       used, otherwise "#include <...>" is the default. Example:
143
144         Module::Build::WithXSpp->new(
145           early_includes => [qw(
146             "mylocalheader.h"
147             <mysystemheader.h>
148           )]
149         )
150

JUMP START FOR THE IMPATIENT

152       There are as many ways to start a new CPAN distribution as there are
153       CPAN distributions. Choose your favourite (I just do "h2xs -An
154       My::Module"), then apply a few changes to your setup:
155
156       • Obliterate any Makefile.PL.
157
158         This is what your Build.PL should look like:
159
160           use strict;
161           use warnings;
162           use 5.006001;
163           use Module::Build::WithXSpp;
164
165           my $build = Module::Build::WithXSpp->new(
166             module_name         => 'My::Module',
167             license             => 'perl',
168             dist_author         => q{John Doe <john_does_mail_address>},
169             dist_version_from   => 'lib/My/Module.pm',
170             build_requires => { 'Test::More' => 0, },
171             extra_typemap_modules => {
172               'ExtUtils::Typemaps::ObjectMap' => '0',
173               # ...
174             },
175           );
176           $build->create_build_script;
177
178         If you need to link against some library "libfoo", add this to the
179         options:
180
181             extra_linker_flags => [qw(-lfoo)],
182
183         There is "extra_compiler_flags", too, if you need it.
184
185       • You create two folders in the main distribution folder: src and xsp.
186
187       • You put any C++ code that you want to build and include in the module
188         into src/. All the typical C(++) file extensions are recognized and
189         will be compiled to object files and linked into the module. And
190         headers in that folder will be accessible for "#include
191         <myheader.h>".
192
193         For good measure, move a copy of ppport.h to that directory.  See
194         Devel::PPPort.
195
196       • You do not write normal XS files. Instead, you write XS++ and put it
197         into the xsp/ folder in files with the ".xsp" extension. Do not
198         worry, you can include verbatim XS blocks in XS++. For details on
199         XS++, see ExtUtils::XSpp.
200
201       • If you need to do any XS type mapping, put your typemaps into a .map
202         file in the "xsp" directory. Alternatively, search CPAN for an
203         appropriate typemap module (cf.  ExtUtils::Typemaps::Default for an
204         explanation).  XS++ typemaps belong into .xspt files in the same
205         directory.
206
207       • In this scheme, lib/ only contains Perl module files (and POD).  If
208         you started from a pure-Perl distribution, don't forget to add these
209         magic two lines to your main module:
210
211           require XSLoader;
212           XSLoader::load('My::Module', $VERSION);
213

SEE ALSO

215       Module::Build upon which this module is based.
216
217       ExtUtils::XSpp implements XS++. The "ExtUtils::XSpp" distribution
218       contains an examples directory with a usage example of this module.
219
220       ExtUtils::Typemaps implements progammatic modification (merging) of
221       C/XS typemaps. "ExtUtils::Typemaps" was renamed from
222       "ExtUtils::Typemap" since the original name conflicted with the core
223       typemap file on case-insensitive file systems.
224
225       ExtUtils::Typemaps::Default explains the concept of having typemaps
226       shipped as modules.
227
228       ExtUtils::Typemaps::ObjectMap is such a typemap module and probably
229       very useful for any XS++ module.
230
231       ExtUtils::Typemaps::STL::String implements simple typemapping for STL
232       "std::string"s.
233

AUTHOR

235       Steffen Mueller <smueller@cpan.org>
236
237       With input and bug fixes from:
238
239       Mattia Barbon
240
241       Shmuel Fomberg
242
243       Florian Schlichting
244
246       Copyright 2010, 2011, 2012, 2013 Steffen Mueller.
247
248       This program is free software; you can redistribute it and/or modify it
249       under the same terms as Perl itself.
250
251
252
253perl v5.38.0                      2023-07-20      Module::Build::WithXSpp(3pm)
Impressum