1 files changed, 206 insertions, 0 deletions
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
new file mode 100644
index 0000000..4af17d5
--- /dev/null
+++ b/doc/source/installation.rst
@@ -0,0 +1,206 @@
+=======================================================
+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.6, 2.7, 3.x (tested with 3.2 to 3.4); 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.6 or 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``).
+
+* `py.test`_ is needed to run the tests of CFFI itself.
+
+.. _`py.test`: http://pypi.python.org/pypi/pytest
+
+Download and Installation:
+
+* https://pypi.python.org/pypi/cffi
+
+* Checksums of the "source" package version 1.12.2:
+
+   - MD5: 4d7dcb6c7c738c15d2ece9bd4c5f86da
+
+   - SHA: 5f579d4980cbcc8aac592721f714ef6a64370ab1
+
+   - SHA256: e113878a446c6228669144ae8a56e268c91b7f1fafae927adc4879d9849e0ea7
+
+* Or grab the most current version from the `Bitbucket page`_:
+  ``hg clone https://bitbucket.org/cffi/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`_ or `Windows 64`_.)
+
+* running the tests: ``py.test  c/  testing/`` (if you didn't
+  install cffi yet, you need first ``python setup_base.py build_ext -f
+  -i``)
+
+.. _`Bitbucket page`: https://bitbucket.org/cffi/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://bitbucket.org/cffi/cffi/src/default/demo
+.. _`testing/cffi1/test_verify1.py`: https://bitbucket.org/cffi/cffi/src/default/testing/cffi1/test_verify1.py
+.. _`testing/cffi0/backend_tests.py`: https://bitbucket.org/cffi/cffi/src/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 (regular 32-bit)
+++++++++++++++++++++++++
+
+Win32 works and is 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
+
+
+Windows 64
+++++++++++
+
+Win64 received very basic testing and we applied a few essential
+fixes in cffi 0.7. The comment above applies for Python 2.7 on 
+Windows 64 as well. Please report any other issue.
+
+Note as usual that this is only about running the 64-bit version of
+Python on the 64-bit OS.  If you're running the 32-bit version (the
+common case apparently), then you're running Win32 as far as we're
+concerned.
+
+.. _`issue 9`: https://bitbucket.org/cffi/cffi/issue/9
+.. _`Python issue 7546`: http://bugs.python.org/issue7546
+
+
+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.