1=encoding utf8 2 3=head1 NAME 4 5Inline::CPP - Write Perl subroutines and classes in C++. 6 7=head1 SYNOPSIS 8 9 use Inline CPP; 10 11 print "9 + 16 = ", add(9, 16), "\n"; 12 print "9 - 16 = ", subtract(9, 16), "\n"; 13 14 __END__ 15 __CPP__ 16 17 int add(int x, int y) { 18 return x + y; 19 } 20 21 int subtract(int x, int y) { 22 return x - y; 23 } 24 25=head1 DESCRIPTION 26 27The L<Inline::CPP> module allows you to put C++ source code directly 28"inline" in a Perl script or module. You code classes or functions in 29C++, and you can use them as if they were written in Perl. 30 31=head1 RATIONALE 32 33"I<We should forget about small efficiencies, say about 97% of the time: 34premature optimization is the root of all evil. Yet we should not pass up our 35opportunities in that critical 3%. A good programmer will not be lulled into 36complacency by such reasoning, he will be wise to look carefully at the 37critical code; but only after that code has been identified>" -- Donald Knuth 38 39L<Inline::CPP> is about that critical 3%. 40 41Tom "Duff's Device" Duff once wrote the following: "I<The alternative to 42genuflecting before the god of code-bumming is finding a better algorithm... 43...If your code is too slow, you must make it faster. If no better algorithm 44is available, you must trim cycles.>" 45 46Often, well written Perl is fast enough. But when one comes across a situation 47where performance isn't fast enough, and no better algorithm exists, getting 48closer to the metal is one way to trim cycles, assuming it's done well. 49L<Inline::CPP> minimizes the pain in binding C++ code to Perl via XS. 50 51Performance can also be evaluated in terms of memory requirements. Perlish 52datastructures are beautifully simple to use, and quite powerful. But this 53beauty and power comes at the cost of memory and speed. If you are finding that 54it is too memory-expensive to hold your data in a Perl array, and a 55disk-based solution is, for whatever reason, not an option, the memory burden 56can be aleviated to some degree by holding the data in a C++ data type. 57 58This can only go so far. But the common saying is that if you consider a 59reasonable amount of memory to hold a data structure, double it, and then 60multiply by ten, you'll have a pretty good feel for how much memory Perl needs 61to hold it. Inline::CPP can facilitate a leaner alternative. 62 63"I<The standard library saves programmers from having to reinvent the wheel.>" 64-- Bjarne Stroustrup 65 66L<Inline::CPP> is also about not reinventing the wheel. 67 68There are many C and C++ libraries already in existence that provide 69functionality that is well tested, well debuged, and well understood. There is 70often no great benefit aside from portability in rewriting such libraries in 71pure Perl. Even re-writing them in XS is cumbersome and prone to bugs. 72Inline::CPP can be used to quickly develop Perl bindings to existing C++ 73libraries. 74 75"I<Brian Ingerson got fed up with writing XS and ended up writing 76a very clever Perl module called L<Inline> to do it for him.>" 77 78Face it, XS has a big fat learning curve, lots of boilerplate, and is easy to 79botch it up in difficult to find ways. Inline::CPP exists to make that process 80easier. By lightening the cognative load and boilerplate drudgery associated 81with pure XS, Inline::CPP can aid the developer in producing less buggy 82extension code. It won't shield you entirely from C<perlguts>, but it will 83take the edge off of it. 84 85=head1 Choosing a C++ Compiler 86 87Inline::CPP just parses the subroutine and class signatures within your C++ 88code and creates bindings to them. Like Inline::C, you will need a suitable 89compiler the first time you run the script. 90 91If you're one of the fortunate majority, you will accept the defaults as you 92install Inline::CPP; the correct C++ compiler and standard libraries will be 93configured for you. If you're one of the unfortunate (and shrinking) minority, 94read on. 95 96Here's the rule: use a C++ compiler that's compatible with the compiler 97which built C<perl>. For instance, if C<perl> was built with C<gcc>, 98use C<g++>. If you're on a Sun or an IRIX box and the system C compiler 99C<cc> built C<perl>, then use the system C++ compiler, C<CC>. 100 101Some compilers actually compile both C and C++ with the same compiler. 102Microsoft's C<cl.exe> is one such compiler -- you pass it the <-TP> flag 103to convince it that you want C++ mode. Hopefully this will be deduced 104by default at install time. 105 106If you're using the GNU C++ compiler, make sure that you have the g++ front 107end installed (some Linux distros don't install it by default, but provide 108it via their package management utilities). 109 110=head1 Using Inline::CPP 111 112Inline::CPP is very similar to Inline::C, and in most cases can be used in 113place of Inline::C without changing a single line of Perl or C code. If you 114haven't done so already, you should stop reading right now and read the 115documentation for L<Inline::C>, including the L<Inline::C-Cookbook>. 116 117This module uses a grammar to parse your C++ code, and binds to functions or 118classes which are recognized. If a function is recognized, it will be available 119from Perl space. If the function's signature is not recognized, it will not 120be available from Perl, but will be available from other functions or classes 121within the C++ code. 122 123The following example shows how C++ snippets map to Perl: 124 125Example 1: 126 127 use Inline CPP => <<'END'; 128 129 using namespace std; 130 131 int doodle() { } 132 133 class Foo { 134 public: 135 Foo(); 136 ~Foo(); 137 138 int get_data() { return data; } 139 void set_data(int a) { data = a; } 140 private: 141 int data; 142 }; 143 144 Foo::Foo() { cout << "creating a Foo()" << endl; } 145 Foo::~Foo() { cout << "deleting a Foo()" << endl; } 146 147 END 148 149After running the code above, your Perl runtime would look similar to if 150following code had been run: 151 152 sub main::doodle { } 153 154 package main::Foo; 155 156 sub new { print "creating a Foo()\n"; bless {}, shift } 157 sub DESTROY { print "deleting a Foo()\n" } 158 159 sub get_data { my $o=shift; $o->{data} } 160 sub set_data { my $o=shift; $o->{data} = shift } 161 162The difference, of course, is that in the latter, Perl does the work. In the 163Inline::CPP example, all function calls get sent off to your C++ code. That 164means that things like this won't work: 165 166 my $obj = new Foo; 167 $obj->{extrafield} = 10; 168 169It doesn't work because C<$obj> is not a blessed hash. It's a blessed 170reference to a C++ object. 171 172=head1 C++ Compilation Phase 173 174The first time you run a program that uses Inline::CPP, the C++ code will be 175compiled into an C<_Inline/> or C<.Inline/> folder within the working directory. 176The first run will incur a startup time penalty associated with compiling C++ 177code. However, the compiled code is cached, and assuming it's not modified, 178subsequent runs will skip the C++ compilation, and startup time will be fast. 179 180=head1 Where to put C++ code 181 182Inline C++ code can reside just about anywhere you want within your Perl code. 183Much of this is documented more fully in the L<Inline> POD, but here are some 184basics: 185 186 use Inline CPP => 'DATA'; 187 188 # Perl code here 189 190 __DATA__ 191 __CPP__ 192 193 // C++ code here. 194 195Or.... 196 197 use Inline CPP => <<'END_CPP'; 198 // C++ code here. 199 END_CPP 200 201Structurally where does it belong? For simple one-off scripts, just put it 202anywhere you want. But in the spirit of code reusability, it's often better to 203simply create a module that houses the functionality build upon C++ code: 204 205 # Foo/Bar.pm 206 package Foo::Bar; 207 use Inline CPP => 'DATA'; 208 209 # Perl code here, including Exporter mantra, if needed. 210 211 __DATA__ 212 __CPP__ 213 // C++ here..... 214 215Where you place your module's file(s) follows the same rules as plain old Perl, 216which is beyond the scope of this POD, but fortunatly no different from what 217you're used to (assuming you're used to writing Perl modules). 218 219Of course, modules can be shared by multiple scripts while only incurring that 220compilation startup penalty one time, ever. 221 222=head1 Basing (CPAN) Distributions on Inline::CPP 223 224Taking the concept of code-reuse one step further, it is entirely possible to 225package a distribution with an Inline::CPP dependency. When the user installs 226the distribution (aka, the module), the C++ code will be compiled during module 227build time, and never again (unless the user upgrades the module). So the user 228will never see the startup lag associated with C++ code compilation. 229 230An example and proof-of-concept for this approach can be found in the CPAN 231module L<Math::Prime::FastSieve>. 232 233This approach involves using L<Inline::MakeMaker>, and is well documented in 234the L<Inline> POD under the heading 235L<Writing Modules with Inline|http://search.cpan.org/perldoc?Inline#Writing_Modules_with_Inline> 236 237However, you may wish to remove the Inline::CPP dependency altogether from the 238code that you bundle into a distribution. This can be done using 239L<InlineX::CPP2XS>, which converts the Inline::CPP generated code to 240Perl XS code, fit for distribution without the Inline::CPP dependency. 241L<InlineX::CPP2XS> includes an example/ directory that actually converts 242Math::Prime::FastSieve to pure XS. 243 244Some extension authors choose to implement first in Inline::CPP, and then 245manually tweak, then copy and paste the resulting XS file into their own 246distribution, with similar effect (and possibly a little finer-grained control) 247to the CPP2XS approach. 248 249=head2 Perl Namespaces 250 251Let's say you use Inline::CPP like this: 252 253 package Some::Foo; 254 use Inline CPP => <<'END_CPP'; 255 256 #include <iostream> 257 using namespace std; 258 259 class Foo { 260 private: 261 int data; 262 public: 263 Foo() { cout << "creating a Foo()" << endl; } 264 ~Foo() { cout << "deleting a Foo()" << endl; } 265 }; 266 267 END_CPP 268 1; 269 270The issue is that the C++ class, "C<Foo>" will be mapped to Perl below the 271C<Some::Foo> namespace, as C<Some::Foo::Foo>, and would need to be instantiated 272like this: C<< my $foo = Some::Foo::Foo->new() >>. This probably isn't what 273the user intended. Use the L<namespace> configuration option to set your base 274namespace: 275 276 use Inline CPP => config => namespace => 'Some'; 277 278Now, C<Foo> falls under the C<Some> heirarchy: C<Some::Foo>, and can be 279instantiated as C<< my $foo = Some::Foo->new() >>. This probably I<is> what the 280user intended. 281 282=head1 C++ Configuration Options 283 284For information on how to specify Inline configuration options, see 285L<Inline>. This section describes each of the configuration options 286available for C/C++. Most of the options correspond either to the MakeMaker 287or XS options of the same name. See L<ExtUtils::MakeMaker> and 288L<perlxs>. 289 290All configuration options, including the word C<config> are case insensitive. 291C<CPP>, and C<DATA> are not configuration options, and are not insensitive to 292case. 293 294=head2 altlibs 295 296Adds a new entry to the end of the list of alternative libraries to 297bind with. MakeMaker will search through this list and use the first 298entry where all the libraries are found. 299 300 use Inline CPP => config => altlibs => '-L/my/other/lib -lfoo'; 301 302See also the C<libs> config option, which appends to the last entry in 303the list. 304 305=head2 auto_include 306 307Specifies extra statements to be automatically included. They will be 308added on to the defaults. A newline char will automatically be added. 309 310 use Inline CPP => config => auto_include => '#include "something.h"'; 311 312=head2 boot 313 314Specifies code to be run when your code is loaded. May not contain any 315blank lines. See L<perlxs> for more information. 316 317 use Inline CPP => config => boot => 'foo();'; 318 319=head2 cc 320 321Specifies which compiler to use. In most cases the configuration default is 322adequate. 323 324 use Inline CPP => config => cc => '/usr/bin/g++-4.6'; 325 326=head2 ccflags 327 328Specifies extra compiler flags. Corresponds to the MakeMaker option. 329 330 use Inline CPP => config => ccflags => '-std=c++11'; 331 332=head2 classes 333 334 use Inline CPP => config => 335 classes => { 'CPPFoo' => 'PerlFoo', 'CPPBar' => 'PerlBar' }; 336 337 use Inline CPP => config => 338 namespace => 'Qux' => 339 classes => { 'CPPFoo' => 'PerlFoo', 'CPPBar' => 'PerlBar' }; 340 341 use Inline CPP => config => 342 classes => sub { 343 my $cpp_class = shift; 344 ... 345 return($perl_package); 346 }; 347 348Override C++ class name. 349 350Under default behavior, a C++ class naming conflict will arise by attempting 351to implement the C++ classes C<Foo::Bar::MyClass> and C<Foo::Qux::MyClass> 352which depend upon one another in some way, because C++ sees both classes as 353named only C<MyClass>. We are unable to solve this C++ conflict by using just 354the C<namespace> config option, because C<namespace> is only applied to the 355Perl package name, not the C++ class name. 356 357In the future, this issue may be solved via Inline::CPP suport for the native 358C++ C<namespace> operator and/or C++ class names which contain the C<::> 359double-colon scope token. 360 361For now, this issue is solved by using the C<classes> config option, which 362accepts either a hash reference or a code reference. When a hash reference 363is provided, each hash key is a C++ class name, and each hash value is a 364corresponding Perl class name. This hash reference serves as a C++-to-Perl 365class name mapping mechanism, and may be used in combination with the 366C<namespace> config option to exercise full control over class and package 367naming. 368 369When a code reference is provided, it must accept as its sole argument the C++ 370class name, and return a single string value containing the generated Perl 371package name. When a code reference is provided for the C<classes> config 372option, the value of the C<namespace> config option is ignored. 373 374The hash reference may be considered a manual mapping method, and the code 375reference an automatic mapping method. 376 377Example file C</tmp/Foo__Bar__MyClass.c>: 378 379 class MyClass { 380 private: 381 int a; 382 public: 383 MyClass() :a(10) {} 384 int fetch () { return a; } 385 }; 386 387Example file C</tmp/Foo__Qux__MyClass.c>: 388 389 #include "/tmp/Foo__Bar__MyClass.c" 390 class MyClass { 391 private: 392 int a; 393 public: 394 MyClass() :a(20) {} 395 int fetch () { return a; } 396 int other_fetch () { MyClass mybar; return mybar.fetch(); } 397 }; 398 399We encounter the C++ class naming conflict when we 400 401 use Inline CPP => '/tmp/Foo__Qux__MyClass.c' => namespace => 'Foo::Qux'; 402 403The C++ compiler sees two C<MyClass> classes and gives a redefinition error: 404 405 _08conflict_encounter_t_9d68.xs:25:7: error: redefinition of ‘class MyClass’ 406 class MyClass { 407 ^ 408 In file included from _08conflict_encounter_t_9d68.xs:24:0: 409 /tmp/Foo__Bar__MyClass.c:1:7: error: previous definition of ‘class MyClass’ 410 class MyClass { 411 ^ 412 413The solution is to rename each C<MyClass> to utilize unique class names, such as 414C<Foo__Bar__MyClass> and C<Foo__Qux__MyClass>, and use the C<classes> config option. 415 416Updated example file C</tmp/Foo__Bar__MyClass.c>: 417 418 class Foo__Bar__MyClass { 419 private: 420 int a; 421 public: 422 Foo__Bar__MyClass() :a(10) {} 423 int fetch () { return a; } 424 }; 425 426Updated example file C</tmp/Foo__Qux__MyClass.c>: 427 428 #include "/tmp/Foo__Bar__MyClass.c" 429 class Foo__Qux__MyClass { 430 private: 431 int a; 432 public: 433 Foo__Qux__MyClass() :a(20) {} 434 int fetch () { return a; } 435 int other_fetch () { Foo__Bar__MyClass mybar; return mybar.fetch(); } 436 }; 437 438First, consider the following updated call to Inline using the hash reference 439method to manually map the namespace and class names. This example does not 440give any C++ errors, and runs correctly in both C++ and Perl: 441 442 use Inline CPP => '/tmp/Foo__Qux__MyClass.c' => 443 namespace => 'Foo' => 444 classes => { 'Foo__Bar__MyClass' => 'Bar::MyClass', 445 'Foo__Qux__MyClass' => 'Qux::MyClass' }; 446 447Next, consider another updated call to Inline using the code reference method 448to automatically map the namespace and class names, which may be deployed across 449more complex codebases. This example automates the mapping of the '__' double- 450underscore to the '::' double-colon scope token. 451 452 use Inline CPP => config => 453 classes => sub { join('::', split('__', shift)); }; 454 455For more information, please see the runnable examples: 456C<t/classes/07conflict_avoid.t> 457C<t/classes/08auto.t> 458C<t/classes/09auto_mixed.t> 459 460=head2 filters 461 462Specifies one (or more, in an array ref) filter which is to be applied to 463the code just prior to parsing. The filters are executed one after another, 464each operating on the output of the previous one. You can pass in a code 465reference or the name of a prepackaged filter. 466 467 use Inline CPP => config => filters => [Strip_POD => \&myfilter]; 468 use Inline CPP => config => filters => 'Preprocess'; # Inline::Filters 469 470The filter may do anything. The code is passed as the first argument, and 471it returns the filtered code. For a set of prefabricated filters, consider 472using L<Inline::Filters>. 473 474=head2 inc 475 476Specifies extra include directories. Corresponds to the MakeMaker 477parameter. 478 479 use Inline CPP => config => inc => '-I/my/path'; 480 481=head2 ld 482 483Specifies the linker to use. 484 485=head2 lddlflags 486 487Specifies which linker flags to use. 488 489NOTE: These flags will completely override the existing flags, instead 490of just adding to them. So if you need to use those too, you must 491respecify them here. 492 493=head2 libs 494 495Specifies external libraries that should be linked into your 496code. Corresponds to the MakeMaker parameter. 497 498 use Inline CPP => config => libs => '-L/your/path -lyourlib'; 499 500Unlike the C<libs> configuration parameter used in Inline::C, successive 501calls to C<libs> append to the previous calls. For example, 502 503 use Inline CPP => config => libs => '-L/my/path', libs => '-lyourlib'; 504 505will work correctly, if correct is for both C<libs> to be in effect. If you 506want to add a new element to the list of possible libraries to link with, use 507the Inline::CPP configuration C<altlibs>. 508 509=head2 make 510 511Specifies the name of the 'C<make>' utility to use. 512 513=head2 myextlib 514 515Specifies a user compiled object that should be linked in. Corresponds 516to the MakeMaker parameter. 517 518 use Inline CPP => config => myextlib => '/your/path/something.o'; 519 520=head2 namespace 521 522 use Inline CPP => config => namespace => 'Foo'; 523 use Inline CPP => config => namespace => 'main'; 524 use Inline CPP => config => namespace => q{}; 525 526Override default base namespace. 527 528Under default behavior, a C++ class C<Foo> created by invoking L<Inline::CPP> 529from C<package Bar> will result in the C++ C<Foo> class being accessible from 530Perl as C<Bar::Foo>. While this default behavior may be desirable in some 531cases, it might be undesirable in others. An example would be creating a C<Foo> 532class while invoking Inline::CPP from package C<Foo>. The resulting class will 533bind to Perl as C<Foo::Foo>, which is probably not what was intended. 534 535This default behavior can be overridden by specifying an alternate base 536C<namespace>. Examples are probably the best way to explain this: 537 538 539 package Foo; 540 use Inline CPP => config => namespace => 'Bar'; 541 use Inline CPP => <<'EOCPP'; 542 543 class Baz { 544 private: 545 int a; 546 public: 547 Baz() :a(20) {} 548 int fetch () { return a; } 549 }; 550 EOCPP 551 552 package main; 553 my $b = Bar::Baz->new(); 554 print $b->fetch, "\n"; # 20. 555 556 557As demonstrated here, the namespace in which "Baz" resides can now be made 558independent of the package from which L<Inline::CPP> has been invoked. 559Consider instead the default behavior: 560 561 562 package Foo; 563 use Inline CPP => <<'EOCPP'; 564 class Foo { 565 private: 566 int a; 567 public: 568 Baz() :a(20) {} 569 int fetch () { return a; } 570 }; 571 EOCPP 572 573 package main; 574 my $b = Foo::Foo->new(); 575 print $b->fetch, "\n"; # 20. 576 577 578It is probably, in this case, undesirable for the C++ class C<Foo> to reside in 579the Perl C<Foo::Foo> namespace. We can fix this by adding our own namespace 580configuration: 581 582 583 package Foo; 584 use Inline CPP => config => namespace => q{}; # Disassociate from 585 # calling package. 586 use Inline CPP => <<'EOCPP'; 587 588 class Baz { 589 private: 590 int a; 591 public: 592 Baz() :a(20) {} 593 int fetch () { return a; } 594 }; 595 EOCPP 596 597 package main; 598 my $b = Foo->new(); 599 print $b->fetch, "\n"; # 20. 600 601=head2 prefix 602 603Specifies a prefix that will automatically be stripped from C++ 604functions when they are bound to Perl. Less useful than in C, because 605C++ mangles its function names to facilitate function overloading. 606 607 use Inline CPP config => prefix => 'ZLIB_'; 608 609This only affects C++ function names, not C++ class names or methods. 610 611=head2 preserve_ellipsis 612 613By default, Inline::CPP replaces C<...> in bound functions with three 614spaces, since the arguments are always passed on the Perl Stack, not on 615the C stack. This is usually desired, since it allows functions with 616no fixed arguments (most compilers require at least one fixed argument). 617 618 use Inline CPP config => preserve_ellipsis => 1; 619or 620 use Inline CPP config => enable => 'preserve_ellipsis'; 621 622For an example of why C<preserve_ellipsis> is normally not needed, see the 623examples section, below. 624 625=head2 std_iostream 626 627By default, Inline::CPP includes the standard iostream header at the top 628of your code. Inline::CPP will try to make the proper selection between 629C<iostream.h> (for older compilers) and C<iostream> (for newer "Standard 630compliant" compilers). 631 632This option assures that C<iostream> (with no C<.h>) is included, which is the 633ANSI-compliant version of the header. For most compilers the use of this 634configuration option should no longer be necessary, as detection is done at 635module install time. The configuration option is still included only to 636maintain backward compatibility with code that used to need it. 637 638 use Inline CPP => config => enable => 'std_iostream'; 639 640=head2 structs 641 642Specifies whether to bind C structs into Perl using L<Inline::Struct>. 643NOTE: Support for this option is experimental. L<Inline::CPP> already binds 644to structs defined in your code. In C++, structs and classes are treated the 645same, except that a struct's initial scope is public, not private. 646L<Inline::Struct> provides autogenerated get/set methods, an overloaded 647constructor, and several other features not available in L<Inline::CPP>. 648 649You can invoke C<structs> in several ways: 650 651 use Inline CPP config => structs => 'Foo'; 652or 653 use Inline CPP config => structs => ['Bar', 'Baz']; 654 655Binds the named structs to Perl. Emits warnings if a struct was requested 656but could not be bound for some reason. 657 658 use Inline CPP config => enable => 'structs'; 659or 660 use Inline CPP config => structs => 1; 661 662Enables binding structs to Perl. All structs which can be bound, will. This 663parameter overrides all requests for particular structs. 664 665 use Inline CPP config => disable => 'structs'; 666or 667 use Inline CPP config => structs => 0; 668 669Disables binding structs to Perl. Overrides any other settings. 670 671See L<Inline::Struct> for more details about how C<Inline::Struct> 672binds C structs to Perl. 673 674=head2 typemaps 675 676Specifies extra typemap files to use. These types will modify the 677behaviour of C++ parsing. Corresponds to the MakeMaker parameter. 678 679 use Inline CPP config => typemaps => '/your/path/typemap'; 680 681=head1 C++-Perl Bindings 682 683This section describes how the C<Perl> variables get mapped to C<C++> 684variables and back again. 685 686Perl uses a stack to pass arguments back and forth to subroutines. When 687a sub is called, it pops off all its arguments from the stack; when it's 688done, it pushes its return values back onto the stack. 689 690XS (Perl's language for creating C or C++ extensions for Perl) uses 691"typemaps" to turn SVs into C types and back again. This is done through 692various XS macro calls, casts, and the Perl API. XS also allows you to 693define your own mappings. 694 695C<Inline::CPP> uses a much simpler approach. It parses the system's 696typemap files and only binds to functions with supported types. You 697can tell C<Inline::CPP> about custom typemap files too. 698 699If you have non-trivial data structures in either C++ or Perl, 700you should probably just pass them as an SV* and do the conversion yourself in 701your C++ function. 702 703In C++, a struct is a class whose default scope is public, not 704private. Inline::CPP binds to structs with this in mind -- get/set 705methods are not yet auto-generated (although this feature may be added to 706an upcoming release). 707 708If you have a C struct, you can use Inline::Struct to allow Perl 709complete access to the internals of the struct. You can create and 710modify structs from inside Perl, as well as pass structs into C++ 711functions and return them from functions. Please note that 712Inline::Struct does not understand any C++ features, so constructors 713and member functions are not supported. See L<Inline::Struct> for more 714details. 715 716=head2 Example 717 718Say you want to use a C++ standard C<string> type. A C++ method that 719takes or returns such will be ignored unless you tell Perl how to map 720it to and from Perl data types. 721 722Put this in a file called F<typemap>: 723 724 TYPEMAP 725 string T_CPPSTRING 726 727 INPUT 728 729 T_CPPSTRING 730 $var = ($type)SvPV_nolen($arg) 731 732 OUTPUT 733 734 T_CPPSTRING 735 sv_setpv((SV*)$arg, $var.c_str()); 736 737Then this script will work: 738 739 use Inline CPP => config => typemaps => "typemap"; 740 use Inline CPP => <<'END'; 741 742 #ifdef __INLINE_CPP_STANDARD_HEADERS 743 #include <string> 744 #else 745 #include <string.h> 746 #endif 747 748 #ifdef __INLINE_CPP_NAMESPACE_STD 749 using namespace std; 750 #endif 751 752 class Abstract { 753 public: 754 virtual string greet2() { 755 string retval = "yo"; 756 return retval; 757 } 758 }; 759 760 class Impl : public Abstract { 761 public: 762 Impl() {} 763 ~Impl() {} 764 }; 765 END 766 767 my $o = Impl->new; 768 print $o->greet2, "\n"; 769 770See F<t/grammar/09purevt.t> for this within the test suite. 771 772=head1 <iostream>, Standard Headers, C++ Namespaces, and Portability Solutions 773 774Inline::CPP automatically includes <iostream>, or <iostream.h>, depending on the 775preference of the target compiler. This distinction illustrates a potential 776problem when trying to write portable code in C++. Legacy C++ 777(pre-ANSI-Standard) used headers named, for example, <iostream.h>. As legacy 778C++ didn't support namespaces, these standard tools were not segregated into a 779separate namespace. 780 781ANSI Standard C++ changed that. Headers were renamed without the '.h' suffix, 782and standard tools were placed in the 'C<std>' namespace. The 783C<using namespace std> and C<using std::string> constructs were also added to 784facilitate working with namespaces. 785 786So pre-Standard (Legacy) C++ code might look like this: 787 788 #include <iostream.h> 789 int main() { 790 cout << "Hello world.\n"; 791 return 0; 792 } 793 794Modern "ANSI Standard C++" compilers would require code like this: 795 796 #include <iostream> 797 using namespace std; 798 int main() { 799 cout << "Hello world.\n"; 800 return 0; 801 } 802 803... or ... 804 805 #include <iostream> 806 int main() { 807 std::cout << "Hello world.\n"; 808 return 0; 809 } 810 811... or even ... 812 813 #include <iostream> 814 int main() { 815 using std::cout; 816 cout << "Hello world.\n"; 817 return 0; 818 } 819 820The first snippet is going to be completely incompabible with the second, third 821or fourth snippets. This is no problem for a C++ developer who knows his target 822compiler. But Perl runs just about everywhere. If similar portability 823(including backward compatibility) is a design goal, Inline::CPP helps by 824providing two C<#define> constants that may be checked to ascertain which style 825of headers are being used. The constants are: 826 827 __INLINE_CPP_STANDARD_HEADERS 828 __INLINE_CPP_NAMESPACE_STD 829 830C<__INLINE_CPP_STANDARD_HEADERS> will be defined if the target compiler 831accepts ANSI Standard headers, such as <iostream>. 832C<__INLINE_CPP_NAMESPACE_STD> will be defined if the target compiler supports 833namespaces. Realistically the two are synonymous; ANSI Standard C++ uses 834namespaces, places standard library tools in the C<std> namespace, and 835invokes headers with the modern (no '.h' suffix) naming convention. So if 836one is defined they both should be. 837 838They can be used as follows: 839 840 use Inline CPP => 'DATA'; 841 842 greet(); 843 844 __DATA__ 845 __CPP__ 846 847 #ifdef __INLINE_CPP_STANDARD_HEADERS 848 #include <string> 849 #else 850 #include <string.h> 851 #endif 852 853 #ifdef __INLINE_CPP_NAMESPACE_STD 854 using namespace std; 855 #endif 856 857 void greet() { 858 string mygreeting = "Hello world!\n"; 859 cout << mygreeting; 860 } 861 862You may decide that you don't care about maintaining portability with 863compilers that lock you in to pre-Standadr C++ -- more than a decade behind us. 864But if you do care (maybe you're basing a CPAN module on Inline::CPP), use these 865preprocessor definitions as a tool in building a widely portable solution. 866 867If you wish, you may C<#undef> either of those defs. The definitions are 868defined before any C<auto_include>s -- even <iostream>. Consequently, you may 869even list C<#undef __INLINE_CPP_....> within an C<auto_include> configuration 870directive. I'm not sure why it would be necessary, but could be useful in 871testing. 872 873Regardless of the header type, Inline::CPP will create the following definition 874in all code it generates: 875 876 #define __INLINE_CPP 1 877 878This can be useful in constructing preprocessor logic that behaves differently 879under Inline::CPP than under a non-Inline::CPP environment. 880 881=head1 EXAMPLES 882 883Here are some examples. 884 885=head2 Example 1 - Farmer Bob 886 887This example illustrates how to use a simple class (C<Farmer>) from 888Perl. One of the new features in Inline::CPP is binding to classes 889with inline method definitions: 890 891 use Inline CPP; 892 893 my $farmer = new Farmer("Ingy", 42); 894 my $slavedriver = 1; 895 while($farmer->how_tired < 420) { 896 $farmer->do_chores($slavedriver); 897 $slavedriver <<= 1; 898 } 899 900 print "Wow! The farmer worked ", $farmer->how_long, " hours!\n"; 901 902 __END__ 903 __CPP__ 904 905 class Farmer { 906 public: 907 Farmer(char *name, int age); 908 ~Farmer(); 909 910 int how_tired() { return tiredness; } 911 int how_long() { return howlong; } 912 void do_chores(int howlong); 913 914 private: 915 char *name; 916 int age; 917 int tiredness; 918 int howlong; 919 }; 920 921 Farmer::Farmer(char *name, int age) { 922 this->name = strdup(name); 923 this->age = age; 924 tiredness = 0; 925 howlong = 0; 926 } 927 928 Farmer::~Farmer() { 929 free(name); 930 } 931 932 void Farmer::do_chores(int hl) { 933 howlong += hl; 934 tiredness += (age * hl); 935 } 936 937=head2 Example 2 - Plane and Simple 938 939This example demonstrates some new features of Inline::CPP: support for 940inheritance and abstract classes. The defined methods of the abstract 941class C<Object> are bound to Perl, but there is no constructor or 942destructor, meaning you cannot instantiate an C<Object>. 943 944The C<Airplane> is a fully-bound class which can be created and 945manipulated from Perl. 946 947 use Inline 'CPP'; 948 949 my $plane = new Airplane; 950 $plane->print; 951 if ($plane->isa("Object")) { print "Plane is an Object!\n"; } 952 unless ($plane->can("fly")) { print "This plane sucks!\n"; } 953 954 __END__ 955 __CPP__ 956 957 using namespace std; 958 959 /* Abstract class (interface) */ 960 class Object { 961 public: 962 virtual void print() { cout << "Object (" << this << ")" << endl; } 963 virtual void info() = 0; 964 virtual bool isa(char *klass) = 0; 965 virtual bool can(char *method) = 0; 966 }; 967 968 class Airplane : public Object { 969 public: 970 Airplane() {} 971 ~Airplane() {} 972 973 virtual void info() { print(); } 974 virtual bool isa(char *klass) { return strcmp(klass, "Object")==0; } 975 virtual bool can(char *method) { 976 bool yes = false; 977 yes |= strcmp(method, "print")==0; 978 yes |= strcmp(method, "info")==0; 979 yes |= strcmp(method, "isa")==0; 980 yes |= strcmp(method, "can")==0; 981 return yes; 982 } 983 }; 984 985=head2 Example 3 - The Ellipsis Abridged 986 987One of the big advantages of Perl over C or C++ is the ability to pass an 988arbitrary number of arguments to a subroutine. You can do it in C, but it's 989messy and difficult to get it right. All of this mess is necessary because 990C doesn't give the programmer access to the stack. Perl, on the other hand, 991gives you access to everything. 992 993Here's a useful function written in Perl that is relatively slow: 994 995 sub average { 996 my $average = 0; 997 for (my $i=0; $i<@_; $i++) { 998 $average *= $i; 999 $average += $_[$i]; 1000 $average /= $i + 1; 1001 } 1002 return $average; 1003 } 1004 1005Here's the same function written in C: 1006 1007 double average() { 1008 Inline_Stack_Vars; 1009 double avg = 0.0; 1010 for (int i=0; i<Inline_Stack_Items; i++) { 1011 avg *= i; 1012 avg += SvNV(Inline_Stack_Item(i)); 1013 avg /= i + 1; 1014 } 1015 return avg; 1016 } 1017 1018Here's a benchmark program that tests which is faster: 1019 1020 use Inline 'CPP'; 1021 my @numbers = map { rand } (1 .. 10000); 1022 my ($a, $stop); 1023 $stop = 200; 1024 if (@ARGV) { 1025 $a = avg(@numbers) while $stop--; 1026 } 1027 else { 1028 $a = average(@numbers) while $stop--; 1029 } 1030 print "The average of 10000 random numbers is: ", $a, "\n"; 1031 1032 sub average { 1033 my $average = 0; 1034 for (my $i=0; $i<@_; $i++) { 1035 $average *= $i; 1036 $average += $_[$i]; 1037 $average /= $i + 1; 1038 } 1039 return $average; 1040 } 1041 1042 __END__ 1043 __CPP__ 1044 1045 double avg(...) { 1046 Inline_Stack_Vars; 1047 double avg = 0.0; 1048 for (int i=0; i<items; i++) { 1049 avg *= i; 1050 avg += SvNV(ST(i)); 1051 avg /= i + 1; 1052 } 1053 return avg; 1054 } 1055 1056Look at the function declaration: 1057 1058 double avg(...) 1059 1060Why didn't we need to use varargs macros to get at the arguments? Why didn't 1061the compiler complain that there were no required arguments? Because 1062Inline::C++ actually compiled this: 1063 1064 double avg( ) 1065 1066When it bound to the function, it noticed the ellipsis and decided to get rid 1067of it. Any function bound to Perl that has an ellipsis in it will have its 1068arguments passed via the Perl stack, not the C stack. That means if you write 1069a function like this: 1070 1071 void myprintf(char *format, ...); 1072 1073then you'd better be reading things from the Perl stack. If you aren't, then 1074specify the PRESERVE_ELLIPSIS option in your script. That will leave the 1075ellipsis in the code for the compiler to whine about. :) 1076 1077=head2 Example 4 - Stacks and Queues 1078 1079Everyone who learns to program with C++ writes a stack and queue class sooner 1080or later. I might as well try it from Inline. But why reinvent the wheel? 1081Perl has a perfectly good Array type, which can easily implement both 1082a Queue and a Stack. 1083 1084This example implements a Queue and a Stack class, and shows off just 1085a few more new features of Inline::CPP: default values to arguments, 1086 1087 use Inline 'CPP'; 1088 1089 my $q = new Queue; 1090 $q->q(50); 1091 $q->q("Where am I?"); 1092 $q->q("In a queue."); 1093 print "There are ", $q->size, " items in the queue\n"; 1094 while($q->size) { 1095 print "About to dequeue: ", $q->peek, "\n"; 1096 print "Actually dequeued: ", $q->dq, "\n"; 1097 } 1098 1099 my $s = new Stack; 1100 $s->push(42); 1101 $s->push("What?"); 1102 print "There are ", $s->size, " items on the stack\n"; 1103 while($s->size) { 1104 print "About to pop: ", $s->peek, "\n"; 1105 print "Actually popped: ", $s->pop, "\n"; 1106 } 1107 1108 __END__ 1109 __CPP__ 1110 1111 class Queue { 1112 public: 1113 Queue(int sz=0) { q = newAV(); if (sz) av_extend(q, sz-1); } 1114 ~Queue() { av_undef(q); } 1115 1116 int size() {return av_len(q) + 1; } 1117 1118 int q(SV *item) { av_push(q, SvREFCNT_inc(item)); return av_len(q)+1; } 1119 SV *dq() { return av_shift(q); } 1120 SV *peek() { return size() ? SvREFCNT_inc(*av_fetch(q,0,0)): &PL_sv_undef;} 1121 1122 private: 1123 AV *q; 1124 }; 1125 1126 class Stack { 1127 public: 1128 Stack(int sz=0) { s = newAV(); if (sz) av_extend(s, sz-1); } 1129 ~Stack() { av_undef(s); } 1130 1131 int size() { return av_len(s) + 1; } 1132 1133 int push(SV *i) { av_push(s, SvREFCNT_inc(i)); return av_len(s)+1; } 1134 SV *pop() { return av_pop(s); } 1135 SV *peek() { return size() ? SvREFCNT_inc(*av_fetch(s,size()-1,0)) : &PL_sv_undef; } 1136 1137 private: 1138 AV *s; 1139 }; 1140 1141=head2 Example 5 - Elipses Revisited (and Overloading or Templates) 1142 1143This example of how to use elipses is adapted from a discussion on Perl Monks. 1144The issue was that someone wanted to call overloaded functions. Perl doesn't 1145understand C++'s overloading rules, and C++ has no idea how Perl intends to call 1146the functions here. So we write a wrapper to take control ourselves: 1147 1148 use Inline CPP => 'DATA'; 1149 1150 say multiadd( 1 ); # No dispatch; just return the value. 1151 say multiadd( 1, 2 ); # Dispatch add( int, int ). 1152 say multiadd( 1, 2, 3 ); # Dispatch add( int, int, int ). 1153 say multiadd( 1, 2, 3, 4 ); # No dispatch; throw an exception. 1154 __DATA__ 1155 __CPP__ 1156 1157 #include <stdexcept> 1158 1159 // Inline::CPP won't create predictable bindings to overloaded functions. 1160 1161 int add ( int a, int b ) { 1162 return a + b; 1163 } 1164 1165 int add ( int a, int b, int c ) { 1166 return a + b + c; 1167 } 1168 1169 // But a function call with elipses can dispatch to overloaded functions since 1170 // no Perl binding is required in reaching those functions. 1171 int multiadd ( SV * a, ... ) { 1172 dXSARGS; // Creates a variable 'items' that contains a paramater count. 1173 try{ 1174 switch ( items ) { 1175 case 1: return SvIV(ST(0)); 1176 case 2: return add( SvIV(ST(0)), SvIV(ST(1)) ); 1177 case 3: return add( SvIV(ST(0)), SvIV(ST(1)), SvIV(ST(2)) ); 1178 default: throw std::runtime_error( 1179 "multiadd() - Too many args in function call" 1180 ); 1181 } 1182 } 1183 catch ( std::runtime_error msg ) { 1184 croak( msg.what() ); // Perl likes croak for exceptions. 1185 } 1186 } 1187 1188Technically one of the versions of add() will bind to Perl, but it's fragile to 1189use it, as the rules for which one binds are undefined. This example overcomes 1190the issue of Perl/XS not understanding overloading by simply wrapping the 1191calls to overloaded functions in a function that does understand. And we use 1192elipses to deal with a variable number of arguments. This same approach can be 1193applied to calling template-generated code as well. 1194 1195=head1 Minimum Perl version requirements 1196 1197As L<Inline> currently requires Perl 5.8.1 or later. Since L<Inline::CPP> 1198depends on L<Inline>, Perl 5.8.1 is also required for L<Inline::CPP>. It's 1199hard to imagine anyone still using a Perl older than 5.8.1 wanting to 1200interface with C++, but if you're in that camp, you'll need to roll back 1201L<Inline> and L<Inline::CPP> to older versions through the magic of backpan. 1202L<Inline::CPP> version 0.25 was still compatible with Perl 5.005_03. Review 1203the Changes file from the L<Inline> distribution to decide which L<Inline> 1204version is appropriate for your pre-5.8.1 Perl. 1205 1206 1207=head1 C++11 Standard 1208 1209Is Inline::CPP is ready for the C++11 standard? The short answer to that 1210question is "Mostly, to the extent that your compiler is C++11 standard 1211compliant." There are two issues to consider. First, what is your compiler 1212capable of (and how to you enable those capabilities), and second, what does 1213Perl need to care about. 1214 1215Taking the first question first (because it's the easiest): Use the C<ccflags> 1216option shown above to pass the proper flag to your compiler to enable C++11 1217features. Most of what your compiler will support, C<Inline::CPP> will deal 1218with. 1219 1220You also may need to use the C<cc> flag to specify a newer version of the 1221compiler, if you happen to have more than one installed -- one that handles 1222C++11 and one that doesn't. 1223 1224Now for the question of what Perl needs to care about: L<Inline::CPP> doesn't 1225look inside of functions or methods. That code is treated as a black box that 1226passes directly through to your compiler. So inside of your functions and 1227methods, feel free to use whatever C++11 features you want. 1228 1229The critical areas are function headers, class definitions, and code that falls 1230outside of functions or classes. Take Enums for example: 1231 1232 enum Colors { RED, GREEN, BLUE }; 1233 1234How should this map to Perl? There's no clear answer. C++11 adds the concept 1235of scope to enums: 1236 1237 enum class Colors { RED, GREEN, BLUE }; 1238 1239How this should bind to Perl becomes even more difficult. The fact is that 1240L<Inline::CPP> won't bind either to Perl. And you're probably better off with 1241that approach than suddenly having $Colors::RED = 0; showing up in your Perl 1242code. Do keep in mind, however, the construct is passed directly through to 1243your C++ compiler, so feel free to use it within the C++ code. It just won't 1244leak out into your Perl namespaces. 1245 1246At the moment the most glaring omission from L<Inline::CPP> of valid C++11 1247syntax is the new "late return type" syntax. C++11 introduced the following 1248legal syntax: 1249 1250 auto add ( int x, int y ) -> int { return x + y; } 1251 1252This omission is only going to be a factor for functions that you want to bind 1253to Perl. If you don't need the function to bind to Perl, the syntax is fine; 1254L<Inline::CPP> just ignores the function. It's important to note that the most 1255common uses of this syntax involve templates and lambdas. Templates don't make 1256sense to L<Inline::CPP> anyway. And lambdas are still fine, because they take 1257place inside of functions, so L<Inline::CPP> doesn't see them anyway. For now, 1258just don't use the late return type syntax in the header of functions that need 1259to bind to Perl. This may get fixed in future revisions to the grammar. 1260 1261Another issue is C<constexpr>: 1262 1263 constexpr int multiply ( int x, int y ) { return x * y; } 1264 1265C<constexpr> isn't recognized by Inline::CPP, so this function won't bind to 1266Perl. I don't I<think> that C<constexpr> functions can even generate external 1267bindings, because they're resolved to a constant at compile-time. They really 1268don't make sense for external use (the compiler can't know how you will call 1269them). Consequently, they'll be ignored by Inline::CPP (and will pass through 1270to your compiler, so they I<will> work I<within> your C++ code). 1271 1272And finally, I<Rvalue references>: 1273 1274L<Inline::CPP> doesn't (yet) understand this: 1275 1276 int x = 100; 1277 1278 int getInt () 1279 { 1280 return x; 1281 } 1282 1283 int && getRvalueInt () 1284 { 1285 return std::move( x ); 1286 } 1287 1288The C<getInt()> function will bind to Perl, but the C<&&> syntax isn't 1289recognized by Inline::CPP, and won't result in a binding being generated. So 1290C<getRvalueInt()> will be invisible to Perl. However, it is perfectly legal to 1291use within your C++ code as long as you don't need it to bind to Perl. 1292 1293Aside from that (as far as I know), you're good to go! Go ahead and use the 1294new version of C<for( auto it: x ) {...}>, or even... 1295 1296 for_each( v.begin(), v.end(), [] (int val) { std::cout << val; } ); 1297 1298The beauty of Inline::CPP is that what goes on inside the black boxes of 1299functions or methods is irrelevant to the binding process. These examples 1300will "just work", assuming your C++ compiler understands them. 1301 1302=head1 BUGS AND DEFICIENCIES 1303 1304There are bound to be bugs in code this uncivilized. If you find one, please 1305file a bug report. Patches are even better. Patches accompanied by tests are 1306like the holy grail. 1307 1308When reporting a bug, please do the following: 1309 1310 - If possible, create a brief stand-alone snippet of code that 1311 demonstrates the issue. 1312 - Use L<Github Issues|https://github.com/daoswald/Inline-CPP/issues> to file 1313 your bug report. 1314 - Patches are always welcome, as are tests that tickle a newfound bug. 1315 1316 - Pull requests should avoid touching irrelevant sections of code/POD, and 1317 tests are required before they can be considered for merge. 1318 1319...or... 1320 1321 - Put "use Inline REPORTBUG;" at the top of your code, or 1322 use the command line option "perl -MInline=REPORTBUG ...". 1323 - Run your code. 1324 - Follow the printed instructions. 1325 1326B<Get involved!> Module development is being tracked on a github 1327repository: L<https://github.com/daoswald/Inline-CPP>. 1328 1329The master branch should always be buildable and usable. 1330 1331Official releases have version numbers in the following format: 'x.xx', and 1332are usually tagged with the CPAN release number. 1333 1334Various development branches will hold a combination of minor commits and CPAN 1335"Developer" releases (these may have a version number formatted as: 1336'x.xx_xxx' to designate a developer-only CPAN release). 1337 1338Most discussion relating to this module (user or developer) occurs on 1339the Inline mailing list, inline.perl.org, and in C<#inline> on C<irc.perl.org>. 1340See L<http://lists.perl.org/list/inline.html> for details on subscribing. 1341 1342Here are some things to watch out for: 1343 1344The grammar used for parsing C++ is still quite simple, and does not 1345allow several features of C++: 1346 1347=over 4 1348 1349=item Templates: You may use template libraries in your code, but 1350L<Inline::CPP> won't know how to parse and bind template definitions. The 1351core problem is that the C++ compiler has no idea how a dynamic language like 1352Perl intends to invoke template-generated code, and thus, cannot know what 1353code to generate from the templates. Keep the templates encapsulated away from 1354the interface that will be exposed to Perl by wrapping calls in functions that 1355will give the compiler a type to work with. 1356 1357=item Operator overloading 1358 1359=item Function overloading -- This is a similar issue to the template problem. 1360Perl doesn't know about C++'s function overload resolution rules. And C++ 1361doesn't know about Perl. XS was never designed to deal with this sort of 1362mismatch. This prevents implementing the I<Rule of Three> for code that is 1363intended to bind with Perl, but because Perl handles your bindings, that's 1364probably not an issue. 1365 1366These three issues (Templates, Operator Overloading, and Function Overloading) 1367are situations where the C++ language and the Perl language simply do not map 1368well to one another. The sooner you get used to this disconnect, the sooner 1369you'll get a feel for what is going to work and what isn't. Templates are how 1370a static language like C++ deals with the concept of generic programming. Perl 1371is such a dynamic language, that templates (which are resolved entirely at 1372compile time) cannot be resolved when called by Perl. Perl's concept of 1373parameter passing is so dynamic that function signatures (which C++ uses in 1374resolving overloads) also can't be mapped meaningfully. There will be other 1375features of C++ don't map into Perl, and vice versa. Consider C++ enums. 1376Should Perl treat them as constants by mapping them via the constant pragma? 1377The answer is unclear, and the fact is they won't be bound into Perl at all. 1378 1379=item Multiple inheritance doesn't work right (yet). 1380 1381=item Multi-dimensional arrays as member data aren't implemented (yet). 1382 1383=item Declaring a paramater type of void isn't implemented. Just use 1384C<int myfunc();> instead of C<int myfunc(void);>. This is C++, not C. It's ok, 1385really. 1386 1387=item Exceptions: While it's ok to throw an exception using 'throw', Perl 1388won't know how to recover from it, and you'll get a core-dump instead of a 1389Perlish death. The solution is simple, C<croak("Message")>. Perl will treat 1390that as a call to C<die>. The fifth example above demonstrates how to get 1391the best of both worlds: C++'s rich exception handling, and Perl's C<die>. 1392 1393The gist of it is this: Catch your throws. And anything that can't be dealt 1394with gracefully, re-throw back to Perl using C<croak>. 1395 1396=back 1397 1398Other grammar problems will probably be discovered. This is Perl, C++, and 1399XS all sealed into one can of worms. But it can be fun, which is a description 1400never applicable to raw XS. 1401 1402=head1 SEE ALSO 1403 1404For general information about how C<Inline> binds code to Perl, see 1405L<Inline>. 1406 1407For information on using C with Perl, see L<Inline::C> and 1408L<Inline::C-Cookbook>. For I<WMTYEWTK>, see L<perlguts>, L<perlxs>, 1409L<perlxstut>, L<perlapi>, and L<perlcall>. The literature for Inline::C 1410(including the cookbook) is relevant and useful in learning Inline::CPP too; 1411just about everything that works for Inline::C will work for Inline::CPP. 1412Rather than reiterate all those great examples here, it's better to just refer 1413the reader to Inline::C and Inline::C-Cookbook's documentation. 1414 1415For converting an Inline::CPP module to pure XS (for simpler 1416distribution), see L<InlineX::CPP2XS>. This method is usually preferable to 1417distributing with an Inline::CPP dependency, however, if you want to do 1418I<that>, read on... 1419 1420L<Math::Prime::FastSieve> is a module based on Inline::CPP (using Inline::CPP 1421and Inline::MakeMaker as dependencies). It serves as a proof of concept, 1422another example of Inline::CPP at work, and a working example of basing a CPAN 1423distribution on Inline::CPP. 1424 1425B<< User and development discussion for Inline modules, including 1426Inline::CPP occurs on the inline.perl.org mailing list. See 1427L<http://lists.perl.org/list/inline.html> to learn how to subscribe. >> 1428 1429The maintainer has found I<Advanced Perl Programming, 2nd Edition> (O'Reilly) 1430helpful, although its discussion is focused on Inline::C. 1431 1432 1433=head1 AUTHOR 1434 1435Neil Watkiss <NEILW@cpan.org> was the original author. 1436 1437David Oswald <DAVIDO@cpan.org> is the current maintainer. 1438David Oswald's Inline::CPP GitHub repo is: 1439L<https://github.com/daoswald/Inline-CPP> 1440 1441Ingy döt Net <INGY@cpan.org> is the author of C<Inline>, and C<Inline::C>. 1442 1443=head1 CONTRIBUTING 1444 1445Issues are tracked, and may be reported at the distribution's 1446L<GitHub issue tracker|https://github.com/daoswald/Inline-CPP/issues>. 1447 1448Contributors may also fork the repo and issue a pull requests. Tests 1449should accompany pull requests, and effort should be made to minimize the 1450scope of any single pull request. 1451 1452Pull requests should not add author names. Non-trivial contributions 1453generally warrant attribution in the log maintained in the C<Changes> 1454file, though the decision to do at the discretion of the maintainers. 1455 1456Please refer to the Artistic 2.0 license, contained in the C<LICENSE> file, 1457included with this distribution for further explanation. 1458 1459=head1 LICENSE AND COPYRIGHT 1460 1461Copyright (c) 2000 - 2003 Neil Watkiss. 1462Copyright (c) 2011 - 2014 David Oswald. 1463 1464All Rights Reserved. This module is free software, licensed under 1465the Artistic license, version 2.0. 1466 1467See http://www.perlfoundation.org/artistic_license_2_0 1468 1469=cut 1470