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