[pypy-commit] cffi cffi-1.0: Finish the docs

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: cffi-1.0
Changeset: r2024:c3dce73733d0
Date: 2015-05-17 10:54 +0200
http://bitbucket.org/cffi/cffi/changeset/c3dce73733d0/

Log:	Finish the docs

diff --git a/TODO b/TODO
--- a/TODO
+++ b/TODO
@@ -1,3 +1,5 @@
 
 
 * cffi_modules, now with the *path as a filename*!
+
+* also support ABI-mode in cffi_modules
diff --git a/doc/source/cdef.rst b/doc/source/cdef.rst
--- a/doc/source/cdef.rst
+++ b/doc/source/cdef.rst
@@ -618,6 +618,39 @@
 Upgrading from CFFI 0.9 to CFFI 1.0
 -----------------------------------
 
-xxx also, remember to remove ``ext_package=".."`` from setup.py, which
-was needed with verify() but is just confusion with set_source().
+CFFI 1.0 is backward-compatible, but it is still a good idea to
+consider moving to the out-of-line approach new in 1.0.  Here are the
+steps.
 
+**ABI mode:** if your CFFI project uses::
+
+    import cffi
+
+    ffi = cffi.FFI()
+    ffi.cdef("stuff")
+    lib = ffi.dlopen("libpath")
+
+and *if* the "stuff" part is big enough that import time is a concern,
+then rewrite it as described in `Out-of-line example (ABI level,
+out-of-line)`__ in the overview_.
+
+.. __: overview.html#out-of-line-abi
+.. _overview: overview.html
+
+
+**API mode:** if your CFFI project uses::
+
+    import cffi
+
+    ffi = cffi.FFI()
+    ffi.cdef("stuff")
+    lib = ffi.verify("real C code")
+
+then you should really rewrite it as described in `Real example (API
+level, out-of-line)`_ in the overview_.  It avoids a number of issues
+that have caused ``ffi.verify()`` to grow a number of extra arguments
+over time.  Also, remember to remove the ``ext_package=".."`` from
+your ``setup.py``, which was needed with ``verify()`` but is just
+creating confusion with ``set_source()``.
+
+.. __: overview.html#real-example
diff --git a/doc/source/overview.rst b/doc/source/overview.rst
--- a/doc/source/overview.rst
+++ b/doc/source/overview.rst
@@ -41,6 +41,8 @@
 there, %s!\n"``.  In general it is ``somestring.encode(myencoding)``.
 
 
+.. _out-of-line-abi:
+
 Out-of-line example (ABI level, out-of-line)
 --------------------------------------------
 
@@ -78,6 +80,20 @@
     lib = ffi.dlopen(None)         # or path to a library
     lib.printf(b"hi there, number %d\n", ffi.cast("int", 2))
 
+For distribution purposes, remember that there is a new
+``_simple_example.py`` file generated.  You can either include it
+statically within your project's source files, or, with Setuptools,
+you can say in the ``setup.py``::
+
+    from setuptools import setup
+
+    setup(
+        ...
+        setup_requires=["cffi>=1.0.0"],
+        cffi_modules=["simple_example_build.py:ffi"],
+        install_requires=["cffi>=1.0.0"],
+    )
+
 
 .. _real-example:
 
@@ -141,7 +157,7 @@
     setup(
         ...
         setup_requires=["cffi>=1.0.0"],
-        cffi_modules=["example_build:ffi"],
+        cffi_modules=["example_build.py:ffi"],
         install_requires=["cffi>=1.0.0"],
     )