| 1 |
CONTRIBUTING |
| 2 |
|
| 3 |
If you have implemented a new feature or fixed a bug then you may make |
| 4 |
a pull request on this project's GitHub repository: |
| 5 |
|
| 6 |
https://github.com/PerlFFI/FFI-Platypus/pulls |
| 7 |
|
| 8 |
This project is developed using Dist::Zilla. The project's git |
| 9 |
repository also comes with the Makefile.PL file necessary for building, |
| 10 |
testing (and even installing if necessary) without Dist::Zilla. Please |
| 11 |
keep in mind though that these files are generated so if changes need |
| 12 |
to be made to those files they should be done through the project's |
| 13 |
dist.ini file. If you do use Dist::Zilla and already have the necessary |
| 14 |
plugins installed, then I encourage you to run dzil test before making |
| 15 |
any pull requests. This is not a requirement, however, I am happy to |
| 16 |
integrate especially smaller patches that need tweaking to fit the |
| 17 |
project standards. I may push back and ask you to write a test case or |
| 18 |
alter the formatting of a patch depending on the amount of time I have |
| 19 |
and the amount of code that your patch touches. |
| 20 |
|
| 21 |
This project's GitHub issue tracker listed above is not Write-Only. If |
| 22 |
you want to contribute then feel free to browse through the existing |
| 23 |
issues and see if there is something you feel you might be good at and |
| 24 |
take a whack at the problem. I frequently open issues myself that I |
| 25 |
hope will be accomplished by someone in the future but do not have time |
| 26 |
to immediately implement myself. |
| 27 |
|
| 28 |
Another good area to help out in is documentation. I try to make sure |
| 29 |
that there is good document coverage, that is there should be |
| 30 |
documentation describing all the public features and warnings about |
| 31 |
common pitfalls, but an outsider's or alternate view point on such |
| 32 |
things would be welcome; if you see something confusing or lacks |
| 33 |
sufficient detail I encourage documentation only pull requests to |
| 34 |
improve things. |
| 35 |
|
| 36 |
The Platypus distribution comes with a test library named libtest that |
| 37 |
is normally automatically built by ./Build test. If you prefer to use |
| 38 |
prove or run tests directly, you can use the ./Build libtest command to |
| 39 |
build it. Example: |
| 40 |
|
| 41 |
% perl Makefile.PL |
| 42 |
% make |
| 43 |
% make ffi-test |
| 44 |
% prove -bv t |
| 45 |
# or an individual test |
| 46 |
% perl -Mblib t/ffi_platypus_memory.t |
| 47 |
|
| 48 |
The build process also respects these environment variables: |
| 49 |
|
| 50 |
FFI_PLATYPUS_DEBUG_FAKE32 |
| 51 |
|
| 52 |
When building Platypus on 32 bit Perls, it will use the Math::Int64 C |
| 53 |
API and make Math::Int64 a prerequisite. Setting this environment |
| 54 |
variable will force Platypus to build with both of those options on a |
| 55 |
64 bit Perl as well. |
| 56 |
|
| 57 |
% env FFI_PLATYPUS_DEBUG_FAKE32=1 perl Makefile.PL |
| 58 |
DEBUG_FAKE32: |
| 59 |
+ making Math::Int64 a prereq |
| 60 |
+ Using Math::Int64's C API to manipulate 64 bit values |
| 61 |
Generating a Unix-style Makefile |
| 62 |
Writing Makefile for FFI::Platypus |
| 63 |
Writing MYMETA.yml and MYMETA.json |
| 64 |
% |
| 65 |
|
| 66 |
FFI_PLATYPUS_NO_ALLOCA |
| 67 |
|
| 68 |
Platypus uses the non-standard and somewhat controversial C function |
| 69 |
alloca by default on platforms that support it. I believe that |
| 70 |
Platypus uses it responsibly to allocate small amounts of memory for |
| 71 |
argument type parameters, and does not use it to allocate large |
| 72 |
structures like arrays or buffers. If you prefer not to use alloca |
| 73 |
despite these precautions, then you can turn its use off by setting |
| 74 |
this environment variable when you run Makefile.PL: |
| 75 |
|
| 76 |
helix% env FFI_PLATYPUS_NO_ALLOCA=1 perl Makefile.PL |
| 77 |
NO_ALLOCA: |
| 78 |
+ alloca() will not be used, even if your platform supports it. |
| 79 |
Generating a Unix-style Makefile |
| 80 |
Writing Makefile for FFI::Platypus |
| 81 |
Writing MYMETA.yml and MYMETA.json |
| 82 |
|
| 83 |
V |
| 84 |
|
| 85 |
When building platypus may hide some of the excessive output when |
| 86 |
probing and building, unless you set V to a true value. |
| 87 |
|
| 88 |
% env V=1 perl Makefile.PL |
| 89 |
% make V=1 |
| 90 |
... |
| 91 |
|
| 92 |
Coding Guidelines |
| 93 |
|
| 94 |
* Do not hesitate to make code contribution. Making useful |
| 95 |
contributions is more important than following byzantine bureaucratic |
| 96 |
coding regulations. We can always tweak things later. |
| 97 |
|
| 98 |
* Please make an effort to follow existing coding style when making |
| 99 |
pull requests. |
| 100 |
|
| 101 |
* The intent of the FFI-Platypus team is to support the same versions |
| 102 |
of Perl that are supported by the Perl toolchain. As of this writing |
| 103 |
that means 5.16 and better. As such, please do not include any code |
| 104 |
that requires a newer version of Perl. |
| 105 |
|
| 106 |
Performance Testing |
| 107 |
|
| 108 |
As Mark Twain was fond of saying there are four types of lies: lies, |
| 109 |
damn lies, statistics and benchmarks. That being said, it can sometimes |
| 110 |
be helpful to compare the runtime performance of Platypus if you are |
| 111 |
making significant changes to the Platypus Core. For that I use |
| 112 |
`FFI-Performance`, which can be found in my GitHub repository here: |
| 113 |
|
| 114 |
https://github.com/Perl5-FFI/FFI-Performance |
| 115 |
|
| 116 |
System integrators |
| 117 |
|
| 118 |
This distribution uses Alien::FFI in fallback mode, meaning if the |
| 119 |
system doesn't provide pkg-config and libffi it will attempt to |
| 120 |
download libffi and build it from source. If you are including Platypus |
| 121 |
in a larger system (for example a Linux distribution) you only need to |
| 122 |
make sure to declare pkg-config or pkgconf and the development package |
| 123 |
for libffi as prereqs for this module. |
| 124 |
|