Author: Armin Rigo <armin.r...@gmail.com> Branch: Changeset: r3078:eccbb9868f8a Date: 2018-01-13 09:47 +0000 http://bitbucket.org/cffi/cffi/changeset/eccbb9868f8a/
Log: Merged in doc-index (pull request #85) split index and lower headings of old versions so TOC looks nicer diff --git a/doc/source/goals.rst b/doc/source/goals.rst new file mode 100644 --- /dev/null +++ b/doc/source/goals.rst @@ -0,0 +1,62 @@ +Goals +----- + +The interface is based on `LuaJIT's FFI`_, and follows a few principles: + +* The goal is to call C code from Python without learning a 3rd language: + existing alternatives require users to learn domain specific language + (Cython_, SWIG_) or API (ctypes_). The CFFI design requires users to know + only C and Python, minimizing the extra bits of API that need to be learned. + +* Keep all the Python-related logic in Python so that you don't need to + write much C code (unlike `CPython native C extensions`_). + +* The preferred way is to work at the level of the API (Application + Programming Interface): the C compiler is called from the declarations + you write to validate and link to the C language constructs. + Alternatively, it is also possible to work at the ABI level + (Application Binary Interface), the way ctypes_ work. + However, on non-Windows platforms, C libraries typically + have a specified C API but not an ABI (e.g. they may + document a "struct" as having at least these fields, but maybe more). + +* Try to be complete. For now some C99 constructs are not supported, + but all C89 should be, including macros (and including macro "abuses", + which you can `manually wrap`_ in saner-looking C functions). + +* Attempt to support both PyPy and CPython, with a reasonable path + for other Python implementations like IronPython and Jython. + +* Note that this project is **not** about embedding executable C code in + Python, unlike `Weave`_. This is about calling existing C libraries + from Python. + +.. _`LuaJIT's FFI`: http://luajit.org/ext_ffi.html +.. _`Cython`: http://www.cython.org +.. _`SWIG`: http://www.swig.org/ +.. _`CPython native C extensions`: http://docs.python.org/extending/extending.html +.. _`native C extensions`: http://docs.python.org/extending/extending.html +.. _`ctypes`: http://docs.python.org/library/ctypes.html +.. _`Weave`: http://wiki.scipy.org/Weave +.. _`manually wrap`: overview.html#abi-versus-api + +Get started by reading `the overview`__. + +.. __: overview.html + + +Comments and bugs +----------------- + +The best way to contact us is on the IRC ``#pypy`` channel of +``irc.freenode.net``. Feel free to discuss matters either there or in +the `mailing list`_. Please report to the `issue tracker`_ any bugs. + +As a general rule, when there is a design issue to resolve, we pick the +solution that is the "most C-like". We hope that this module has got +everything you need to access C code and nothing more. + +--- the authors, Armin Rigo and Maciej Fijalkowski + +.. _`issue tracker`: https://bitbucket.org/cffi/cffi/issues +.. _`mailing list`: https://groups.google.com/forum/#!forum/python-cffi diff --git a/doc/source/index.rst b/doc/source/index.rst --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -6,13 +6,10 @@ code from Python, based on C-like declarations that you can often copy-paste from header files or documentation. -* Goals_ - - * `Comments and bugs`_ - .. toctree:: :maxdepth: 2 + goals whatsnew installation overview @@ -22,65 +19,4 @@ embedding -Goals ------ -The interface is based on `LuaJIT's FFI`_, and follows a few principles: - -* The goal is to call C code from Python without learning a 3rd language: - existing alternatives require users to learn domain specific language - (Cython_, SWIG_) or API (ctypes_). The CFFI design requires users to know - only C and Python, minimizing the extra bits of API that need to be learned. - -* Keep all the Python-related logic in Python so that you don't need to - write much C code (unlike `CPython native C extensions`_). - -* The preferred way is to work at the level of the API (Application - Programming Interface): the C compiler is called from the declarations - you write to validate and link to the C language constructs. - Alternatively, it is also possible to work at the ABI level - (Application Binary Interface), the way ctypes_ work. - However, on non-Windows platforms, C libraries typically - have a specified C API but not an ABI (e.g. they may - document a "struct" as having at least these fields, but maybe more). - -* Try to be complete. For now some C99 constructs are not supported, - but all C89 should be, including macros (and including macro "abuses", - which you can `manually wrap`_ in saner-looking C functions). - -* Attempt to support both PyPy and CPython, with a reasonable path - for other Python implementations like IronPython and Jython. - -* Note that this project is **not** about embedding executable C code in - Python, unlike `Weave`_. This is about calling existing C libraries - from Python. - -.. _`LuaJIT's FFI`: http://luajit.org/ext_ffi.html -.. _`Cython`: http://www.cython.org -.. _`SWIG`: http://www.swig.org/ -.. _`CPython native C extensions`: http://docs.python.org/extending/extending.html -.. _`native C extensions`: http://docs.python.org/extending/extending.html -.. _`ctypes`: http://docs.python.org/library/ctypes.html -.. _`Weave`: http://wiki.scipy.org/Weave -.. _`manually wrap`: overview.html#abi-versus-api - -Get started by reading `the overview`__. - -.. __: overview.html - - -Comments and bugs ------------------ - -The best way to contact us is on the IRC ``#pypy`` channel of -``irc.freenode.net``. Feel free to discuss matters either there or in -the `mailing list`_. Please report to the `issue tracker`_ any bugs. - -As a general rule, when there is a design issue to resolve, we pick the -solution that is the "most C-like". We hope that this module has got -everything you need to access C code and nothing more. - ---- the authors, Armin Rigo and Maciej Fijalkowski - -.. _`issue tracker`: https://bitbucket.org/cffi/cffi/issues -.. _`mailing list`: https://groups.google.com/forum/#!forum/python-cffi diff --git a/doc/source/whatsnew.rst b/doc/source/whatsnew.rst --- a/doc/source/whatsnew.rst +++ b/doc/source/whatsnew.rst @@ -95,8 +95,11 @@ .. __: http://bugs.python.org/issue31105 +Older Versions +============== + v1.10.1 -======= +------- (only released inside PyPy 5.8.0) @@ -107,7 +110,7 @@ v1.10 -===== +----- * Issue #295: use calloc() directly instead of PyObject_Malloc()+memset() to handle ffi.new() with a default @@ -169,7 +172,7 @@ v1.9 -==== +---- * Structs with variable-sized arrays as their last field: now we track the length of the array after ``ffi.new()`` is called, just like we @@ -204,7 +207,7 @@ v1.8.3 -====== +------ * When passing a ``void *`` argument to a function with a different pointer type, or vice-versa, the cast occurs automatically, like in C. @@ -217,7 +220,7 @@ v1.8.2 -====== +------ * Issue #283: fixed ``ffi.new()`` on structures/unions with nested anonymous structures/unions, when there is at least one union in @@ -226,7 +229,7 @@ v1.8.1 -====== +------ * CPython 3.x: experimental: the generated C extension modules now use the "limited API", which means that, as a compiled .so/.dll, it should @@ -241,7 +244,7 @@ v1.8 -==== +---- * Removed the restriction that ``ffi.from_buffer()`` cannot be used on byte strings. Now you can get a ``char *`` out of a byte string, @@ -255,7 +258,7 @@ v1.7 -==== +---- * ``ffi.gc(p, None)`` removes the destructor on an object previously created by another call to ``ffi.gc()`` @@ -284,7 +287,7 @@ v1.6 -==== +---- * `ffi.list_types()`_ @@ -307,13 +310,13 @@ v1.5.2 -====== +------ * Fix 1.5.1 for Python 2.6. v1.5.1 -====== +------ * A few installation-time tweaks (thanks Stefano!) @@ -325,7 +328,7 @@ v1.5.0 -====== +------ * Support for `using CFFI for embedding`__. @@ -333,13 +336,13 @@ v1.4.2 -====== +------ Nothing changed from v1.4.1. v1.4.1 -====== +------ * Fix the compilation failure of cffi on CPython 3.5.0. (3.5.1 works; some detail changed that makes some underscore-starting macros @@ -349,7 +352,7 @@ v1.4.0 -====== +------ * A `better way to do callbacks`__ has been added (faster and more portable, and usually cleaner). It is a mechanism for the @@ -390,7 +393,7 @@ v1.3.1 -====== +------ * The optional typedefs (``bool``, ``FILE`` and all Windows types) were not always available from out-of-line FFI objects. @@ -406,7 +409,7 @@ v1.3.0 -====== +------ * Added `ffi.memmove()`_. @@ -441,13 +444,13 @@ v1.2.1 -====== +------ Nothing changed from v1.2.0. v1.2.0 -====== +------ * Out-of-line mode: ``int a[][...];`` can be used to declare a structure field or global variable which is, simultaneously, of total length @@ -500,14 +503,14 @@ v1.1.2 -====== +------ * ``ffi.gc()``: fixed a race condition in multithreaded programs introduced in 1.1.1 v1.1.1 -====== +------ * Out-of-line mode: ``ffi.string()``, ``ffi.buffer()`` and ``ffi.getwinerror()`` didn't accept their arguments as keyword @@ -525,7 +528,7 @@ v1.1.0 -====== +------ * Out-of-line API mode: we can now declare integer types with ``typedef int... foo_t;``. The exact size and signedness of ``foo_t`` @@ -558,13 +561,13 @@ v1.0.3 -====== +------ * Same as 1.0.2, apart from doc and test fixes on some platforms. v1.0.2 -====== +------ * Variadic C functions (ending in a "..." argument) were not supported in the out-of-line ABI mode. This was a bug---there was even a @@ -574,7 +577,7 @@ v1.0.1 -====== +------ * ``ffi.set_source()`` crashed if passed a ``sources=[..]`` argument. Fixed by chrippa on pull request #60. @@ -587,7 +590,7 @@ v1.0.0 -====== +------ * The main news item is out-of-line module generation: _______________________________________________ pypy-commit mailing list pypy-commit@python.org https://mail.python.org/mailman/listinfo/pypy-commit