Author: Armin Rigo <ar...@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"],
)
_______________________________________________
pypy-commit mailing list
pypy-commit@python.org
https://mail.python.org/mailman/listinfo/pypy-commit
