CONTRIBUTING If you have implemented a new feature or fixed a bug then you may make a pull request on this project's GitHub repository: https://github.com/PerlFFI/FFI-Platypus/pulls This project is developed using Dist::Zilla. The project's git repository also comes with the Makefile.PL file necessary for building, testing (and even installing if necessary) without Dist::Zilla. Please keep in mind though that these files are generated so if changes need to be made to those files they should be done through the project's dist.ini file. If you do use Dist::Zilla and already have the necessary plugins installed, then I encourage you to run dzil test before making any pull requests. This is not a requirement, however, I am happy to integrate especially smaller patches that need tweaking to fit the project standards. I may push back and ask you to write a test case or alter the formatting of a patch depending on the amount of time I have and the amount of code that your patch touches. This project's GitHub issue tracker listed above is not Write-Only. If you want to contribute then feel free to browse through the existing issues and see if there is something you feel you might be good at and take a whack at the problem. I frequently open issues myself that I hope will be accomplished by someone in the future but do not have time to immediately implement myself. Another good area to help out in is documentation. I try to make sure that there is good document coverage, that is there should be documentation describing all the public features and warnings about common pitfalls, but an outsider's or alternate view point on such things would be welcome; if you see something confusing or lacks sufficient detail I encourage documentation only pull requests to improve things. The Platypus distribution comes with a test library named libtest that is normally automatically built by ./Build test. If you prefer to use prove or run tests directly, you can use the ./Build libtest command to build it. Example: % perl Makefile.PL % make % make ffi-test % prove -bv t # or an individual test % perl -Mblib t/ffi_platypus_memory.t The build process also respects these environment variables: FFI_PLATYPUS_DEBUG_FAKE32 When building Platypus on 32 bit Perls, it will use the Math::Int64 C API and make Math::Int64 a prerequisite. Setting this environment variable will force Platypus to build with both of those options on a 64 bit Perl as well. % env FFI_PLATYPUS_DEBUG_FAKE32=1 perl Makefile.PL DEBUG_FAKE32: + making Math::Int64 a prereq + Using Math::Int64's C API to manipulate 64 bit values Generating a Unix-style Makefile Writing Makefile for FFI::Platypus Writing MYMETA.yml and MYMETA.json % FFI_PLATYPUS_NO_ALLOCA Platypus uses the non-standard and somewhat controversial C function alloca by default on platforms that support it. I believe that Platypus uses it responsibly to allocate small amounts of memory for argument type parameters, and does not use it to allocate large structures like arrays or buffers. If you prefer not to use alloca despite these precautions, then you can turn its use off by setting this environment variable when you run Makefile.PL: helix% env FFI_PLATYPUS_NO_ALLOCA=1 perl Makefile.PL NO_ALLOCA: + alloca() will not be used, even if your platform supports it. Generating a Unix-style Makefile Writing Makefile for FFI::Platypus Writing MYMETA.yml and MYMETA.json V When building platypus may hide some of the excessive output when probing and building, unless you set V to a true value. % env V=1 perl Makefile.PL % make V=1 ... Coding Guidelines * Do not hesitate to make code contribution. Making useful contributions is more important than following byzantine bureaucratic coding regulations. We can always tweak things later. * Please make an effort to follow existing coding style when making pull requests. * The intent of the FFI-Platypus team is to support the same versions of Perl that are supported by the Perl toolchain. As of this writing that means 5.16 and better. As such, please do not include any code that requires a newer version of Perl. Performance Testing As Mark Twain was fond of saying there are four types of lies: lies, damn lies, statistics and benchmarks. That being said, it can sometimes be helpful to compare the runtime performance of Platypus if you are making significant changes to the Platypus Core. For that I use `FFI-Performance`, which can be found in my GitHub repository here: https://github.com/Perl5-FFI/FFI-Performance System integrators This distribution uses Alien::FFI in fallback mode, meaning if the system doesn't provide pkg-config and libffi it will attempt to download libffi and build it from source. If you are including Platypus in a larger system (for example a Linux distribution) you only need to make sure to declare pkg-config or pkgconf and the development package for libffi as prereqs for this module.