Debian Codegraph @

docs/source/installation.rst

raw
1 Installation and use with setuptools
2 ====================================
3
4 Since Cppy is nothing else than a collection of header that are only compiled
5 when used, installing it is extremely straightforward using pip::
6
7 $ pip install cppy
8
9 If you want to run the development version, you can install directly from
10 GitHub::
11
12 $ pip install git+https://github.com/nucleic/cppy
13
14
15 Using Cppy in an extensions
16 ---------------------------
17
18 To use Cppy in your extension (written in C++), you simply need to include it.
19
20 .. code:: c++
21
22 #include <cppy/cppy.h>
23
24 Cppy includes Python.h so when including cppy.h you do not need to also include
25 Python.h.
26
27 Every functions, classes exposed by Cppy are stored in the `cppy` namespace.
28
29 .. code:: c++
30
31 cppy::ptr obj_ptr( PyUnicode_FromString("test") )
32
33
34 Use with setuptools
35 -------------------
36
37 Cppy is only needed during the installation step of the projects using it.
38
39 When using a PEP 517 compatible build system, one can simply specify cppy as a
40 build requirement in ```pyproject.toml``::
41
42 [build-system]
43 requires = ["setuptools>=42", "wheel", "cppy>=1.2"]
44
45 Which will ensure that cppy is available in setup.py allowing to import it at the
46 top level of the module. This allows in particular to import ``CppyBuildExt``
47 which enforces the use of C++11 and provide access to the cppy headers. On Windows,
48 FH4 Exception Handling can be disabled by setting the CPPY_DISABLE_FH4 environment
49 variable. This avoids requiring VCRUNTIME140_1.dll
50
51 In one is not using a PEP 517 compatible install, the following example setup.py
52 script illustrates how to use Cppy without requiring it to be installed before
53 `setup.py` is run.
54
55 .. code:: python
56
57 from setuptools import setup, Extension
58 from setuptools.command.build_ext import build_ext
59
60 ext_modules = [
61 Extension(
62 'project',
63 ['module.cpp'],
64 include_dirs=['.'],
65 language='c++',
66 ),
67 ]
68
69 class BuildExt(build_ext):
70
71 def build_extensions(self):
72
73 # Delayed import of cppy to let setup_requires install it if
74 # necessary
75 import cppy
76
77 ct = self.compiler.compiler_type
78 for ext in self.extensions:
79 # cppy.get_include() collect the path of the header files
80 ext.include_dirs.insert(0, cppy.get_include())
81 build_ext.build_extensions(self)
82
83 setup(
84 name='project',
85 python_requires='>=3.5',
86 setup_requires=['cppy'],
87 ext_modules=ext_modules,
88 cmdclass={'build_ext': BuildExt},
89 )