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.

      * Platypus supports all production Perl releases since 5.8.1. For
      that reason, please do not introduce 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/PerlFFI/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.