1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
=======================================================
Installation and Status
=======================================================
Quick installation for CPython (cffi is distributed with PyPy):
* ``pip install cffi``
* or get the source code via the `Python Package Index`__.
.. __: http://pypi.python.org/pypi/cffi
In more details:
This code has been developed on Linux, but should work on any POSIX
platform as well as on Windows 32 and 64. (It relies occasionally on
libffi, so it depends on libffi being bug-free; this may not be fully
the case on some of the more exotic platforms.)
CFFI supports CPython 2.7, 3.x (tested with 3.6 to 3.9); and is
distributed with PyPy (CFFI 1.0 is distributed with and requires
PyPy 2.6).
The core speed of CFFI is better than ctypes, with import times being
either lower if you use the post-1.0 features, or much higher if you
don't. The wrapper Python code you typically need to write around the
raw CFFI interface slows things down on CPython, but not unreasonably
so. On PyPy, this wrapper code has a minimal impact thanks to the JIT
compiler. This makes CFFI the recommended way to interface with C
libraries on PyPy.
Requirements:
* CPython 2.7 or 3.x, or PyPy (PyPy 2.0 for the earliest
versions of CFFI; or PyPy 2.6 for CFFI 1.0).
* in some cases you need to be able to compile C extension modules.
On non-Windows platforms, this usually means installing the package
``python-dev``. Refer to the appropriate docs for your OS.
* on CPython, on non-Windows platforms, you also need to install
``libffi-dev`` in order to compile CFFI itself.
* pycparser >= 2.06: https://github.com/eliben/pycparser (automatically
tracked by ``pip install cffi``).
* `pytest`_ is needed to run the tests of CFFI itself.
.. _`pytest`: http://pypi.python.org/pypi/pytest
Download and Installation:
* https://pypi.python.org/pypi/cffi
* Checksums of the "source" package version 1.15.1:
- MD5: f493860a6e98cd0c4178149568a6b4f6
- SHA1: c42a46cd11f6153f299cf10e9c236e8b2a143c21
- SHA256: d400bfb9a37b1351253cb402671cea7e89bdecc294e8016a707f6d1d8ac934f9
* Or grab the most current version from the `Heptapod page`_:
``hg clone https://foss.heptapod.net/pypy/cffi``
* ``python setup.py install`` or ``python setup_base.py install``
(should work out of the box on Linux or Windows; see below for
`MacOS X`_.)
* running the tests: ``pytest c/ testing/`` (if you didn't
install cffi yet, you need first ``python setup_base.py build_ext -f
-i``)
.. _`Heptapod page`: https://foss.heptapod.net/pypy/cffi
Demos:
* The `demo`_ directory contains a number of small and large demos
of using ``cffi``.
* The documentation below might be sketchy on details; for now the
ultimate reference is given by the tests, notably
`testing/cffi1/test_verify1.py`_ and `testing/cffi0/backend_tests.py`_.
.. _`demo`: https://foss.heptapod.net/pypy/cffi/-/tree/branch/default/demo
.. _`testing/cffi1/test_verify1.py`: https://foss.heptapod.net/pypy/cffi/-/blob/branch/default/testing/cffi1/test_verify1.py
.. _`testing/cffi0/backend_tests.py`: https://foss.heptapod.net/pypy/cffi/-/blob/branch/default/testing/cffi0/backend_tests.py
Platform-specific instructions
------------------------------
``libffi`` is notoriously messy to install and use --- to the point that
CPython includes its own copy to avoid relying on external packages.
CFFI does the same for Windows, but not for other platforms (which should
have their own working libffi's).
Modern Linuxes work out of the box thanks to ``pkg-config``. Here are some
(user-supplied) instructions for other platforms.
MacOS X
+++++++
**Homebrew** (Thanks David Griffin for this)
1) Install homebrew: http://brew.sh
2) Run the following commands in a terminal
::
brew install pkg-config libffi
PKG_CONFIG_PATH=/usr/local/opt/libffi/lib/pkgconfig pip install cffi
Alternatively, **on OS/X 10.6** (Thanks Juraj Sukop for this)
For building libffi you can use the default install path, but then, in
``setup.py`` you need to change::
include_dirs = []
to::
include_dirs = ['/usr/local/lib/libffi-3.0.11/include']
Then running ``python setup.py build`` complains about "fatal error: error writing to -: Broken pipe", which can be fixed by running::
ARCHFLAGS="-arch i386 -arch x86_64" python setup.py build
as described here_.
.. _here: http://superuser.com/questions/259278/python-2-6-1-pycrypto-2-3-pypi-package-broken-pipe-during-build
Windows (32/64-bit)
+++++++++++++++++++
Win32 and Win64 work and are tested at least each official release.
The recommended C compiler compatible with Python 2.7 is this one:
http://www.microsoft.com/en-us/download/details.aspx?id=44266
There is a known problem with distutils on Python 2.7, as
explained in https://bugs.python.org/issue23246, and the same
problem applies whenever you want to run compile() to build a dll with
this specific compiler suite download.
``import setuptools`` might help, but YMMV
For Python 3.4 and beyond:
https://www.visualstudio.com/en-us/downloads/visual-studio-2015-ctp-vs
Linux and OS/X: UCS2 versus UCS4
++++++++++++++++++++++++++++++++
This is about getting an ImportError about ``_cffi_backend.so`` with a
message like ``Symbol not found: _PyUnicodeUCS2_AsASCIIString``. This
error occurs in Python 2 as soon as you mix "ucs2" and "ucs4" builds of
Python. It means that you are now running a Python compiled with
"ucs4", but the extension module ``_cffi_backend.so`` was compiled by a
different Python: one that was running "ucs2". (If the opposite problem
occurs, you get an error about ``_PyUnicodeUCS4_AsASCIIString``
instead.)
If you are using ``pyenv``, then see
https://github.com/yyuu/pyenv/issues/257.
More generally, the solution that should always work is to download the
sources of CFFI (instead of a prebuilt binary) and make sure that you
build it with the same version of Python than the one that will use it.
For example, with virtualenv:
* ``virtualenv ~/venv``
* ``cd ~/path/to/sources/of/cffi``
* ``~/venv/bin/python setup.py build --force`` # forcing a rebuild to
make sure
* ``~/venv/bin/python setup.py install``
This will compile and install CFFI in this virtualenv, using the
Python from this virtualenv.
NetBSD
++++++
You need to make sure you have an up-to-date version of libffi, which
fixes some bugs.
|
