view release on metacpan or  search on metacpan

inc/inc_Module-Build/Module/Build/WithXSpp.pm  view on Meta::CPAN

option when creating a C<Module::Build::WithXSpp> object to list headers
to include before the perl headers. If such a supplied header file starts with
a double quote, C<#include "..."> is used, otherwise C<#include E<lt>...E<gt>>
is the default. Example:

  Module::Build::WithXSpp->new(
    early_includes => [qw(
      "mylocalheader.h"
      <mysystemheader.h>
    )]
  )

=head1 JUMP START FOR THE IMPATIENT

There are as many ways to start a new CPAN distribution as there
are CPAN distributions. Choose your favourite
(I just do C<h2xs -An My::Module>), then apply a few
changes to your setup:

=over 2

=item *

Obliterate any F<Makefile.PL>.

This is what your F<Build.PL> should look like:

  use strict;
  use warnings;
  use 5.006001;
  use Module::Build::WithXSpp;
  
  my $build = Module::Build::WithXSpp->new(
    module_name         => 'My::Module',
    license             => 'perl',
    dist_author         => q{John Doe <john_does_mail_address>},
    dist_version_from   => 'lib/My/Module.pm',
    build_requires => { 'Test::More' => 0, },
    extra_typemap_modules => {
      'ExtUtils::Typemaps::ObjectMap' => '0',
      # ...
    },
  );
  $build->create_build_script;

If you need to link against some library C<libfoo>, add this to
the options:

    extra_linker_flags => [qw(-lfoo)],

There is C<extra_compiler_flags>, too, if you need it.

=item *

You create two folders in the main distribution folder:
F<src> and F<xsp>.

=item *

You put any C++ code that you want to build and include
in the module into F<src/>. All the typical C(++) file
extensions are recognized and will be compiled to object files
and linked into the module. And headers in that folder will
be accessible for C<#include E<lt>myheader.hE<gt>>.

For good measure, move a copy of F<ppport.h> to that directory.
See L<Devel::PPPort>.

=item *

You do not write normal XS files. Instead, you write XS++ and
put it into the F<xsp/> folder in files with the C<.xsp>
extension. Do not worry, you can include verbatim XS blocks
in XS++. For details on XS++, see L<ExtUtils::XSpp>.

=item *

If you need to do any XS type mapping, put your typemaps
into a F<.map> file in the C<xsp> directory. Alternatively,
search CPAN for an appropriate typemap module (cf.
L<ExtUtils::Typemaps::Default> for an explanation).
XS++ typemaps belong into F<.xspt> files in the same directory.

=item *

In this scheme, F<lib/> only contains Perl module files (and POD).
If you started from a pure-Perl distribution, don't forget to add
these magic two lines to your main module:

  require XSLoader;
  XSLoader::load('My::Module', $VERSION);

=back

=head1 SEE ALSO

L<Module::Build> upon which this module is based.

L<ExtUtils::XSpp> implements XS++. The C<ExtUtils::XSpp> distribution
contains an F<examples> directory with a usage example of this module.

L<ExtUtils::Typemaps> implements progammatic modification (merging)
of C/XS typemaps. C<ExtUtils::Typemaps> was renamed from C<ExtUtils::Typemap>
since the original name conflicted with the core F<typemap> file on
case-insensitive file systems.

L<ExtUtils::Typemaps::Default> explains the concept of having typemaps
shipped as modules.

L<ExtUtils::Typemaps::ObjectMap> is such a typemap module and
probably very useful for any XS++ module.

L<ExtUtils::Typemaps::STL::String> implements simple typemapping for
STL C<std::string>s.

=head1 AUTHOR

Steffen Mueller <smueller@cpan.org>

With input and bug fixes from:

Mattia Barbon

Shmuel Fomberg

Florian Schlichting

=head1 COPYRIGHT AND LICENSE

Copyright 2010, 2011, 2012 Steffen Mueller.

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

=cut