Debian Codegraph @

CONTRIBUTING

raw
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