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