# Installation and use with setuptools

Since Cppy is nothing else than a collection of header that are only compiled when used, installing it is extremely straightforward using pip:

    $ pip install cppy

If you want to run the development version, you can install directly from GitHub:

    $ pip install git+https://github.com/nucleic/cppy

## Using Cppy in an extensions

To use Cppy in your extension (written in C++), you simply need to include it.

    #include <cppy/cppy.h>

Cppy includes Python.h so when including cppy.h you do not need to also include Python.h.

Every functions, classes exposed by Cppy are stored in the cppy namespace.

    cppy::ptr obj_ptr( PyUnicode_FromString("test") )

## Use with setuptools

Cppy is only needed during the installation step of the projects using it.

When using a PEP 517 compatible build system, one can simply specify cppy as a build requirement in ``pyproject.toml`:

    [build-system]
    requires =  ["setuptools>=42", "wheel", "cppy>=1.2"]

Which will ensure that cppy is available in setup.py allowing to import it at the top level of the module. This allows in particular to import `CppyBuildExt` which enforces the use of C++11 and provide access to the cppy headers. On Windows, FH4 Exception Handling can be disabled by setting the CPPY_DISABLE_FH4 environment variable. This avoids requiring VCRUNTIME140_1.dll

In one is not using a PEP 517 compatible install, the following example setup.py script illustrates how to use Cppy without requiring it to be installed before setup.py is run.

    from setuptools import setup, Extension
    from setuptools.command.build_ext import build_ext

    ext_modules = [
        Extension(
            'project',
            ['module.cpp'],
            include_dirs=['.'],
            language='c++',
        ),
    ]

    class BuildExt(build_ext):

        def build_extensions(self):

            # Delayed import of cppy to let setup_requires install it if
            # necessary
            import cppy

            ct = self.compiler.compiler_type
            for ext in self.extensions:
                # cppy.get_include() collect the path of the header files
                ext.include_dirs.insert(0, cppy.get_include())
            build_ext.build_extensions(self)

    setup(
        name='project',
        python_requires='>=3.5',
        setup_requires=['cppy'],
        ext_modules=ext_modules,
        cmdclass={'build_ext': BuildExt},
    )