1CONTRIBUTING 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 * Platypus supports all production Perl releases since 5.8.1. For 102 that reason, please do not introduce any code that requires a newer 103 version of Perl. 104 105 Performance Testing 106 107 As Mark Twain was fond of saying there are four types of lies: lies, 108 damn lies, statistics and benchmarks. That being said, it can sometimes 109 be helpful to compare the runtime performance of Platypus if you are 110 making significant changes to the Platypus Core. For that I use 111 `FFI-Performance`, which can be found in my GitHub repository here: 112 113 https://github.com/PerlFFI/FFI-Performance 114 115 System integrators 116 117 This distribution uses Alien::FFI in fallback mode, meaning if the 118 system doesn't provide pkg-config and libffi it will attempt to 119 download libffi and build it from source. If you are including Platypus 120 in a larger system (for example a Linux distribution) you only need to 121 make sure to declare pkg-config or pkgconf and the development package 122 for libffi as prereqs for this module. 123 124