[pypy-commit] cffi default: Rename 'ffi' to 'ffibuilder' in the docs and in a few demos, when
arigo
pypy.commits at gmail.com
Sun Jun 5 17:03:37 EDT 2016
Author: Armin Rigo <arigo at tunes.org>
Branch:
Changeset: r2708:c455de81882f
Date: 2016-06-05 23:01 +0200
http://bitbucket.org/cffi/cffi/changeset/c455de81882f/
Log: Rename 'ffi' to 'ffibuilder' in the docs and in a few demos, when it
is used in out-of-line builders. I think it makes things clearer,
particularly in examples where the two 'ffi' are close together (and
even sometimes used in the same sentence...)
diff --git a/demo/bsdopendirtype_build.py b/demo/bsdopendirtype_build.py
--- a/demo/bsdopendirtype_build.py
+++ b/demo/bsdopendirtype_build.py
@@ -1,7 +1,7 @@
from cffi import FFI
-ffi = FFI()
-ffi.cdef("""
+ffibuilder = FFI()
+ffibuilder.cdef("""
typedef ... DIR;
struct dirent {
unsigned char d_type; /* type of file */
@@ -14,10 +14,10 @@
static const int DT_BLK, DT_CHR, DT_DIR, DT_FIFO, DT_LNK, DT_REG, DT_SOCK;
""")
-ffi.set_source("_bsdopendirtype", """
+ffibuilder.set_source("_bsdopendirtype", """
#include <sys/types.h>
#include <dirent.h>
""")
if __name__ == '__main__':
- ffi.compile()
+ ffibuilder.compile(verbose=True)
diff --git a/demo/bsdopendirtype_setup.py b/demo/bsdopendirtype_setup.py
--- a/demo/bsdopendirtype_setup.py
+++ b/demo/bsdopendirtype_setup.py
@@ -6,7 +6,7 @@
py_modules=["bsdopendirtype"],
setup_requires=["cffi>=1.0.dev0"],
cffi_modules=[
- "bsdopendirtype_build.py:ffi",
+ "bsdopendirtype_build.py:ffibuilder",
],
install_requires=["cffi>=1.0.dev0"], # should maybe be "cffi-backend" only?
zip_safe=False,
diff --git a/demo/embedding.py b/demo/embedding.py
--- a/demo/embedding.py
+++ b/demo/embedding.py
@@ -1,12 +1,12 @@
import cffi
-ffi = cffi.FFI()
+ffibuilder = cffi.FFI()
-ffi.embedding_api("""
+ffibuilder.embedding_api("""
int add(int, int);
""")
-ffi.embedding_init_code("""
+ffibuilder.embedding_init_code("""
from _embedding_cffi import ffi
print("preparing") # printed once
@@ -16,6 +16,6 @@
return x + y
""")
-ffi.set_source("_embedding_cffi", "")
+ffibuilder.set_source("_embedding_cffi", "")
-ffi.compile(verbose=True)
+ffibuilder.compile(verbose=True)
diff --git a/demo/gmp_build.py b/demo/gmp_build.py
--- a/demo/gmp_build.py
+++ b/demo/gmp_build.py
@@ -6,9 +6,9 @@
# http://bazaar.launchpad.net/~tolot-solar-empire/+junk/gmpy_cffi/files
#
-ffi = cffi.FFI()
+ffibuilder = cffi.FFI()
-ffi.cdef("""
+ffibuilder.cdef("""
typedef struct { ...; } MP_INT;
typedef MP_INT mpz_t[1];
@@ -19,8 +19,8 @@
""")
-ffi.set_source('_gmp_cffi', "#include <gmp.h>",
+ffibuilder.set_source('_gmp_cffi', "#include <gmp.h>",
libraries=['gmp', 'm'])
if __name__ == '__main__':
- ffi.compile(verbose=True)
+ ffibuilder.compile(verbose=True)
diff --git a/demo/setup.py b/demo/setup.py
deleted file mode 100644
--- a/demo/setup.py
+++ /dev/null
@@ -1,12 +0,0 @@
-#
-# A minimal example of setup.py to install a Python module
-# together with the custom C extension module generated by CFFI.
-#
-
-from distutils.core import setup
-from distutils.extension import Extension
-import bsdopendirtype
-
-setup(name='bsdopendirtype',
- py_modules=['bsdopendirtype'],
- ext_modules=[bsdopendirtype.ffi.verifier.get_extension()])
diff --git a/doc/source/cdef.rst b/doc/source/cdef.rst
--- a/doc/source/cdef.rst
+++ b/doc/source/cdef.rst
@@ -29,12 +29,12 @@
# in a separate file "package/foo_build.py"
import cffi
- ffi = cffi.FFI()
- ffi.set_source("package._foo", None)
- ffi.cdef("C-like declarations")
+ ffibuilder = cffi.FFI()
+ ffibuilder.set_source("package._foo", None)
+ ffibuilder.cdef("C-like declarations")
if __name__ == "__main__":
- ffi.compile()
+ ffibuilder.compile()
Running ``python foo_build.py`` produces a file ``_foo.py``, which
can then be imported in the main program:
@@ -57,12 +57,12 @@
# in a separate file "package/foo_build.py"
import cffi
- ffi = cffi.FFI()
- ffi.set_source("package._foo", "real C code") # <=
- ffi.cdef("C-like declarations with '...'")
+ ffibuilder = cffi.FFI()
+ ffibuilder.set_source("package._foo", "real C code") # <=
+ ffibuilder.cdef("C-like declarations with '...'")
if __name__ == "__main__":
- ffi.compile(verbose=True)
+ ffibuilder.compile(verbose=True)
Running ``python foo_build.py`` produces a file ``_foo.c`` and
invokes the C compiler to turn it into a file ``_foo.so`` (or
@@ -91,7 +91,7 @@
setup(
...,
- ext_modules=[foo_build.ffi.distutils_extension()],
+ ext_modules=[foo_build.ffibuilder.distutils_extension()],
)
For Setuptools (out-of-line, but works in ABI or API mode;
@@ -105,7 +105,7 @@
setup(
...,
setup_requires=["cffi>=1.0.0"],
- cffi_modules=["package/foo_build.py:ffi"],
+ cffi_modules=["package/foo_build.py:ffibuilder"],
install_requires=["cffi>=1.0.0"],
)
@@ -121,9 +121,13 @@
page `Using the ffi/lib objects`_ describes the common functionality.
It is what you get in the ``from package._foo import ffi`` lines above.
On the other hand, the extended ``FFI`` class is the one you get from
-``import cffi; ffi = cffi.FFI()``. It has the same functionality (for
-in-line use), but also the extra methods described below (to prepare
-the FFI).
+``import cffi; ffi_or_ffibuilder = cffi.FFI()``. It has the same
+functionality (for in-line use), but also the extra methods described
+below (to prepare the FFI). NOTE: We use the name ``ffibuilder``
+instead of ``ffi`` in the out-of-line context, when the code is about
+producing a ``_foo.so`` file; this is an attempt to distinguish it
+from the different ``ffi`` object that you get by later saying
+``from _foo import ffi``.
.. _`Using the ffi/lib objects`: using.html
@@ -143,15 +147,16 @@
apart from writes to global variables. Also, ``lib.__dict__`` does
not work before version 1.2 or if ``lib`` happens to declare a name
called ``__dict__`` (use instead ``dir(lib)``). The same is true
-for ``lib.__class__`` before version 1.4.
+for ``lib.__class__``, ``lib.__all__`` and ``lib.__name__`` added
+in successive versions.
.. _cdef:
-ffi.cdef(): declaring types and functions
------------------------------------------
+ffi/ffibuilder.cdef(): declaring types and functions
+----------------------------------------------------
-**ffi.cdef(source)**: parses the given C source.
+**ffi/ffibuilder.cdef(source)**: parses the given C source.
It registers all the functions, types, constants and global variables in
the C source. The types can be used immediately in ``ffi.new()`` and
other functions. Before you can access the functions and global
@@ -326,18 +331,18 @@
``ffi.dlopen(ctypes.util.find_library('c'))``.
-ffi.set_source(): preparing out-of-line modules
------------------------------------------------
+ffibuilder.set_source(): preparing out-of-line modules
+------------------------------------------------------
-**ffi.set_source(module_name, c_header_source, [\*\*keywords...])**:
+**ffibuilder.set_source(module_name, c_header_source, [\*\*keywords...])**:
prepare the ffi for producing out-of-line an external module called
``module_name``. *New in version 1.0.*
-``ffi.set_source()`` by itself does not write any file, but merely
+``ffibuilder.set_source()`` by itself does not write any file, but merely
records its arguments for later. It can therefore be called before or
-after ``ffi.cdef()``.
+after ``ffibuilder.cdef()``.
-In **ABI mode,** you call ``ffi.set_source(module_name, None)``. The
+In **ABI mode,** you call ``ffibuilder.set_source(module_name, None)``. The
argument is the name (or dotted name inside a package) of the Python
module to generate. In this mode, no C compiler is called.
@@ -384,7 +389,7 @@
.. code-block:: python
- ffi.set_source("mymodule", '''
+ ffibuilder.set_source("mymodule", '''
extern "C" {
int somefunc(int somearg) { return real_cpp_func(somearg); }
}
@@ -504,22 +509,23 @@
different declarations).
-ffi.compile() etc.: compiling out-of-line modules
--------------------------------------------------
+ffibuilder.compile() etc.: compiling out-of-line modules
+--------------------------------------------------------
You can use one of the following functions to actually generate the
-.py or .c file prepared with ``ffi.set_source()`` and ``ffi.cdef()``.
+.py or .c file prepared with ``ffibuilder.set_source()`` and
+``ffibuilder.cdef()``.
Note that these function won't overwrite a .py/.c file with exactly
the same content, to preserve the mtime. In some cases where you need
the mtime to be updated anyway, delete the file before calling the
functions.
-**ffi.compile(tmpdir='.', verbose=False):**
+**ffibuilder.compile(tmpdir='.', verbose=False):**
explicitly generate the .py or .c file,
and (if .c) compile it. The output file is (or are) put in the
directory given by ``tmpdir``. In the examples given here, we use
-``if __name__ == "__main__": ffi.compile()`` in the build scripts---if
+``if __name__ == "__main__": ffibuilder.compile()`` in the build scripts---if
they are directly executed, this makes them rebuild the .py/.c file in
the current directory. (Note: if a package is specified in the call
to ``set_source()``, then a corresponding subdirectory of the ``tmpdir``
@@ -530,13 +536,13 @@
compiler. (This parameter might be changed to True by default in a
future release.)
-**ffi.emit_python_code(filename):** generate the given .py file (same
-as ``ffi.compile()`` for ABI mode, with an explicitly-named file to
+**ffibuilder.emit_python_code(filename):** generate the given .py file (same
+as ``ffibuilder.compile()`` for ABI mode, with an explicitly-named file to
write). If you choose, you can include this .py file pre-packaged in
your own distributions: it is identical for any Python version (2 or
3).
-**ffi.emit_c_code(filename):** generate the given .c file (for API
+**ffibuilder.emit_c_code(filename):** generate the given .c file (for API
mode) without compiling it. Can be used if you have some other method
to compile it, e.g. if you want to integrate with some larger build
system that will compile this file for you. You can also distribute
@@ -545,25 +551,25 @@
if produced on a different OS, with a different version of CPython, or
with PyPy; it is done with generating the appropriate ``#ifdef``).
-**ffi.distutils_extension(tmpdir='build', verbose=True):** for
+**ffibuilder.distutils_extension(tmpdir='build', verbose=True):** for
distutils-based ``setup.py`` files. Calling this creates the .c file
if needed in the given ``tmpdir``, and returns a
``distutils.core.Extension`` instance.
For Setuptools, you use instead the line
-``cffi_modules=["path/to/foo_build.py:ffi"]`` in ``setup.py``. This
+``cffi_modules=["path/to/foo_build.py:ffibuilder"]`` in ``setup.py``. This
line asks Setuptools to import and use a helper provided by CFFI,
which in turn executes the file ``path/to/foo_build.py`` (as with
-``execfile()``) and looks up its global variable called ``ffi``. You
+``execfile()``) and looks up its global variable called ``ffibuilder``. You
can also say ``cffi_modules=["path/to/foo_build.py:maker"]``, where
``maker`` names a global function; it is called with no argument and
is supposed to return a ``FFI`` object.
-ffi.include(): combining multiple CFFI interfaces
--------------------------------------------------
+ffi/ffibuilder.include(): combining multiple CFFI interfaces
+------------------------------------------------------------
-**ffi.include(other_ffi)**: includes the typedefs, structs, unions,
+**ffi/ffibuilder.include(other_ffi)**: includes the typedefs, structs, unions,
enums and constants defined in another FFI instance. This is meant
for large projects where one CFFI-based interface depends on some
types declared in a different CFFI-based interface.
@@ -574,9 +580,10 @@
object. (You can write several ``cdef()`` calls over the same ``ffi``
from several Python files, if one file would be too large.)
-For out-of-line modules, the ``ffi.include(other_ffi)`` line should
-occur in the build script, and the ``other_ffi`` argument should be
-another FFI that comes from another build script. When the two build
+For out-of-line modules, the ``ffibuilder.include(other_ffibuilder)``
+line should
+occur in the build script, and the ``other_ffibuilder`` argument should be
+another FFI instance that comes from another build script. When the two build
scripts are turned into generated files, say ``_ffi.so`` and
``_other_ffi.so``, then importing ``_ffi.so`` will internally cause
``_other_ffi.so`` to be imported. At that point, the real
@@ -722,11 +729,11 @@
check. Be sure to have other means of clearing the ``tmpdir``
whenever you change your sources.
-* ``source_extension`` has the same meaning as in ``ffi.set_source()``.
+* ``source_extension`` has the same meaning as in ``ffibuilder.set_source()``.
* The optional ``flags`` argument (ignored on Windows) defaults to
``ffi.RTLD_NOW``; see ``man dlopen``. (With
- ``ffi.set_source()``, you would use ``sys.setdlopenflags()``.)
+ ``ffibuilder.set_source()``, you would use ``sys.setdlopenflags()``.)
* The optional ``relative_to`` argument is useful if you need to list
local files passed to the C compiler::
diff --git a/doc/source/embedding.rst b/doc/source/embedding.rst
--- a/doc/source/embedding.rst
+++ b/doc/source/embedding.rst
@@ -51,16 +51,16 @@
# file plugin_build.py
import cffi
- ffi = cffi.FFI()
+ ffibuilder = cffi.FFI()
with open('plugin.h') as f:
- ffi.embedding_api(f.read())
+ ffibuilder.embedding_api(f.read())
- ffi.set_source("my_plugin", '''
+ ffibuilder.set_source("my_plugin", '''
#include "plugin.h"
''')
- ffi.embedding_init_code("""
+ ffibuilder.embedding_init_code("""
from my_plugin import ffi
@ffi.def_extern()
@@ -69,7 +69,7 @@
return p.x + p.y
""")
- ffi.compile(target="plugin-1.5.*", verbose=True)
+ ffibuilder.compile(target="plugin-1.5.*", verbose=True)
Running the code above produces a *DLL*, i,e, a dynamically-loadable
library. It is a file with the extension ``.dll`` on Windows,
@@ -82,7 +82,7 @@
Here are some details about the methods used above:
-* **ffi.embedding_api(source):** parses the given C source, which
+* **ffibuilder.embedding_api(source):** parses the given C source, which
declares functions that you want to be exported by the DLL. It can
also declare types, constants and global variables that are part of
the C-level API of your DLL.
@@ -95,9 +95,9 @@
The global variables, on the other hand, are not automatically
produced. You have to write their definition explicitly in
- ``ffi.set_source()``, as regular C code (see the point after next).
+ ``ffibuilder.set_source()``, as regular C code (see the point after next).
-* **ffi.embedding_init_code(python_code):** this gives
+* **ffibuilder.embedding_init_code(python_code):** this gives
initialization-time Python source code. This code is copied
("frozen") inside the DLL. At runtime, the code is executed when
the DLL is first initialized, just after Python itself is
@@ -105,14 +105,14 @@
extra "built-in" module that can be loaded magically without
accessing any files, with a line like "``from my_plugin import ffi,
lib``". The name ``my_plugin`` comes from the first argument to
- ``ffi.set_source()``. This module represents "the caller's C world"
+ ``ffibuilder.set_source()``. This module represents "the caller's C world"
from the point of view of Python.
The initialization-time Python code can import other modules or
packages as usual. You may have typical Python issues like needing
to set up ``sys.path`` somehow manually first.
- For every function declared within ``ffi.embedding_api()``, the
+ For every function declared within ``ffibuilder.embedding_api()``, the
initialization-time Python code or one of the modules it imports
should use the decorator ``@ffi.def_extern()`` to attach a
corresponding Python function to it.
@@ -128,7 +128,7 @@
contains code that calls ``exit()``, for example if importing
``site`` fails. This may be worked around in the future.
-* **ffi.set_source(c_module_name, c_code):** set the name of the
+* **ffibuilder.set_source(c_module_name, c_code):** set the name of the
module from Python's point of view. It also gives more C code which
will be included in the generated C code. In trivial examples it
can be an empty string. It is where you would ``#include`` some
@@ -136,14 +136,14 @@
``CFFI_DLLEXPORT`` is available to this C code: it expands to the
platform-specific way of saying "the following declaration should be
exported from the DLL". For example, you would put "``extern int
- my_glob;``" in ``ffi.embedding_api()`` and "``CFFI_DLLEXPORT int
- my_glob = 42;``" in ``ffi.set_source()``.
+ my_glob;``" in ``ffibuilder.embedding_api()`` and "``CFFI_DLLEXPORT int
+ my_glob = 42;``" in ``ffibuilder.set_source()``.
- Currently, any *type* declared in ``ffi.embedding_api()`` must also
+ Currently, any *type* declared in ``ffibuilder.embedding_api()`` must also
be present in the ``c_code``. This is automatic if this code
contains a line like ``#include "plugin.h"`` in the example above.
-* **ffi.compile([target=...] [, verbose=True]):** make the C code and
+* **ffibuilder.compile([target=...] [, verbose=True]):** make the C code and
compile it. By default, it produces a file called
``c_module_name.dll``, ``c_module_name.dylib`` or
``c_module_name.so``, but the default can be changed with the
@@ -155,7 +155,7 @@
"``plugin-1.5.*``".
For more complicated cases, you can call instead
- ``ffi.emit_c_code("foo.c")`` and compile the resulting ``foo.c``
+ ``ffibuilder.emit_c_code("foo.c")`` and compile the resulting ``foo.c``
file using other means. CFFI's compilation logic is based on the
standard library ``distutils`` package, which is really developed
and tested for the purpose of making CPython extension modules, not
@@ -189,29 +189,29 @@
need to have your Python code call C code, read more about
`Embedding and Extending`_ below.
-* ``ffi.embedding_api(source)``: follows the same syntax as
- ``ffi.cdef()``, `documented here.`__ You can use the "``...``"
+* ``ffibuilder.embedding_api(source)``: follows the same syntax as
+ ``ffibuilder.cdef()``, `documented here.`__ You can use the "``...``"
syntax as well, although in practice it may be less useful than it
is for ``cdef()``. On the other hand, it is expected that often the
- C sources that you need to give to ``ffi.embedding_api()`` would be
+ C sources that you need to give to ``ffibuilder.embedding_api()`` would be
exactly the same as the content of some ``.h`` file that you want to
give to users of your DLL. That's why the example above does this::
with open('foo.h') as f:
- ffi.embedding_api(f.read())
+ ffibuilder.embedding_api(f.read())
- Note that a drawback of this approach is that ``ffi.embedding_api()``
+ Note that a drawback of this approach is that ``ffibuilder.embedding_api()``
doesn't support ``#ifdef`` directives. You may have to use a more
convoluted expression like::
with open('foo.h') as f:
lines = [line for line in f if not line.startswith('#')]
- ffi.embedding_api(''.join(lines))
+ ffibuilder.embedding_api(''.join(lines))
As in the example above, you can also use the same ``foo.h`` from
- ``ffi.set_source()``::
+ ``ffibuilder.set_source()``::
- ffi.set_source('module_name', '#include "foo.h"')
+ ffibuilder.set_source('module_name', '#include "foo.h"')
.. __: using.html#working
@@ -281,7 +281,7 @@
* You can avoid the ``LD_LIBRARY_PATH`` issue if you compile
``libmy_plugin.so`` with the path hard-coded inside in the first
place. On Linux, this is done by ``gcc -Wl,-rpath=/some/path``. You
- would put this option in ``ffi.set_source("my_plugin", ...,
+ would put this option in ``ffibuilder.set_source("my_plugin", ...,
extra_link_args=['-Wl,-rpath=/some/path/to/libpypy'])``. The path can
start with ``$ORIGIN`` to mean "the directory where
``libmy_plugin.so`` is". You can then specify a path relative to that
@@ -354,7 +354,7 @@
You might have some issues with the file name: for example, on
Windows, Python expects the file to be called ``c_module_name.pyd``,
but the CFFI-made DLL is called ``target.dll`` instead. The base name
-``target`` is the one specified in ``ffi.compile()``, and on Windows
+``target`` is the one specified in ``ffibuilder.compile()``, and on Windows
the extension is ``.dll`` instead of ``.pyd``. You have to rename or
copy the file, or on POSIX use a symlink.
@@ -371,7 +371,8 @@
The embedding mode is not incompatible with the non-embedding mode of
CFFI.
-You can use *both* ``ffi.embedding_api()`` and ``ffi.cdef()`` in the
+You can use *both* ``ffibuilder.embedding_api()`` and
+``ffibuilder.cdef()`` in the
same build script. You put in the former the declarations you want to
be exported by the DLL; you put in the latter only the C functions and
types that you want to share between C and Python, but not export from
@@ -380,10 +381,10 @@
As an example of that, consider the case where you would like to have
a DLL-exported C function written in C directly, maybe to handle some
cases before calling Python functions. To do that, you must *not* put
-the function's signature in ``ffi.embedding_api()``. (Note that this
-requires more hacks if you use ``ffi.embedding_api(f.read())``.) You must
-only write the custom function definition in ``ffi.set_source()``, and
-prefix it with the macro CFFI_DLLEXPORT:
+the function's signature in ``ffibuilder.embedding_api()``. (Note that this
+requires more hacks if you use ``ffibuilder.embedding_api(f.read())``.)
+You must only write the custom function definition in
+``ffibuilder.set_source()``, and prefix it with the macro CFFI_DLLEXPORT:
.. code-block:: c
@@ -399,11 +400,11 @@
.. code-block:: python
- ffi.cdef("""
+ ffibuilder.cdef("""
extern "Python" int mycb(int);
""")
- ffi.set_source("my_plugin", """
+ ffibuilder.set_source("my_plugin", """
static int mycb(int); /* the callback: forward declaration, to make
it accessible from the C code that follows */
@@ -433,7 +434,7 @@
inserted around it. It only happens when ``myfunc()`` calls
``mycb()``.
-As the above explanation hints, this is how ``ffi.embedding_api()``
+As the above explanation hints, this is how ``ffibuilder.embedding_api()``
actually implements function calls that directly invoke Python code;
here, we have merely decomposed it explicitly, in order to add some
custom C code in the middle.
diff --git a/doc/source/overview.rst b/doc/source/overview.rst
--- a/doc/source/overview.rst
+++ b/doc/source/overview.rst
@@ -66,19 +66,20 @@
# file "simple_example_build.py"
- # Note: this particular example fails before version 1.0.2
- # because it combines variadic function and ABI level.
+ # Note: we instantiate the same 'cffi.FFI' class as in the previous
+ # example, but call the result 'ffibuilder' now instead of 'ffi';
+ # this is to avoid confusion with the other 'ffi' object you get below
from cffi import FFI
- ffi = FFI()
- ffi.set_source("_simple_example", None)
- ffi.cdef("""
+ ffibuilder = FFI()
+ ffibuilder.set_source("_simple_example", None)
+ ffibuilder.cdef("""
int printf(const char *format, ...);
""")
if __name__ == "__main__":
- ffi.compile()
+ ffibuilder.compile(verbose=True)
Running it once produces ``_simple_example.py``. Your main program
only imports this generated module, not ``simple_example_build.py``
@@ -115,7 +116,7 @@
setup(
...
setup_requires=["cffi>=1.0.0"],
- cffi_modules=["simple_example_build.py:ffi"],
+ cffi_modules=["simple_example_build.py:ffibuilder"],
install_requires=["cffi>=1.0.0"],
)
@@ -131,9 +132,9 @@
# file "example_build.py"
from cffi import FFI
- ffi = FFI()
+ ffibuilder = FFI()
- ffi.set_source("_example",
+ ffibuilder.set_source("_example",
""" // passed to the real C compiler
#include <sys/types.h>
#include <pwd.h>
@@ -142,7 +143,7 @@
# (more arguments like setup.py's Extension class:
# include_dirs=[..], extra_objects=[..], and so on)
- ffi.cdef(""" // some declarations from the man page
+ ffibuilder.cdef(""" // some declarations from the man page
struct passwd {
char *pw_name;
...; // literally dot-dot-dot
@@ -151,7 +152,7 @@
""")
if __name__ == "__main__":
- ffi.compile()
+ ffibuilder.compile(verbose=True)
You need to run the ``example_build.py`` script once to generate
"source code" into the file ``_example.c`` and compile this to a
@@ -189,7 +190,7 @@
setup(
...
setup_requires=["cffi>=1.0.0"],
- cffi_modules=["example_build.py:ffi"],
+ cffi_modules=["example_build.py:ffibuilder"],
install_requires=["cffi>=1.0.0"],
)
@@ -252,11 +253,11 @@
# file "example_build.py"
from cffi import FFI
- ffi = FFI()
+ ffibuilder = FFI()
- ffi.cdef("int foo(int *, int *, int);")
+ ffibuilder.cdef("int foo(int *, int *, int);")
- ffi.set_source("_example",
+ ffibuilder.set_source("_example",
"""
static int foo(int *buffer_in, int *buffer_out, int x)
{
@@ -265,7 +266,7 @@
""")
if __name__ == "__main__":
- ffi.compile()
+ ffibuilder.compile(verbose=True)
.. code-block:: python
@@ -301,15 +302,15 @@
.. code-block:: python
import cffi
- ffi = cffi.FFI()
+ ffibuilder = cffi.FFI()
- ffi.embedding_api("""
+ ffibuilder.embedding_api("""
int do_stuff(int, int);
""")
- ffi.set_source("my_plugin", "")
+ ffibuilder.set_source("my_plugin", "")
- ffi.embedding_init_code("""
+ ffibuilder.embedding_init_code("""
from my_plugin import ffi
@ffi.def_extern()
@@ -318,7 +319,7 @@
return x + y
""")
- ffi.compile(target="plugin-1.5.*", verbose=True)
+ ffibuilder.compile(target="plugin-1.5.*", verbose=True)
This simple example creates ``plugin-1.5.dll`` or ``plugin-1.5.so`` as
a DLL with a single exported function, ``do_stuff()``. You execute
diff --git a/doc/source/ref.rst b/doc/source/ref.rst
--- a/doc/source/ref.rst
+++ b/doc/source/ref.rst
@@ -333,7 +333,7 @@
is garbage-collected. The object is modified in-place, and the
function returns ``None``. *New in version 1.7: ffi.gc(ptr, None)*
-Note that this should be avoided for large memory allocations or
+Note that ``ffi.gc()`` should be avoided for large memory allocations or
for limited resources. This is particularly true on PyPy: its GC does
not know how much memory or how many resources the returned ``ptr``
holds. It will only run its GC when enough memory it knows about has
diff --git a/doc/source/using.rst b/doc/source/using.rst
--- a/doc/source/using.rst
+++ b/doc/source/using.rst
@@ -358,7 +358,7 @@
"``...;``" in the ``cdef()``; you need to declare it completely in
``cdef()``. You can work around these limitations by writing a C
function with a simpler signature in the C header code passed to
-``ffi.set_source()``, and have this C function call the real one.
+``ffibuilder.set_source()``, and have this C function call the real one.
Aside from these limitations, functions and callbacks can receive and
return structs.
@@ -450,12 +450,12 @@
In the builder script, declare in the cdef a function prefixed with
``extern "Python"``::
- ffi.cdef("""
+ ffibuilder.cdef("""
extern "Python" int my_callback(int, int);
void library_function(int(*callback)(int, int));
""")
- ffi.set_source("_my_example", """
+ ffibuilder.set_source("_my_example", """
#include <some_library.h>
""")
@@ -515,14 +515,14 @@
Then you would write this in the build script::
- ffi.cdef("""
+ ffibuilder.cdef("""
typedef ... event_t;
typedef void (*event_cb_t)(event_t *evt, void *userdata);
void event_cb_register(event_cb_t cb, void *userdata);
extern "Python" void my_event_callback(event_t *, void *);
""")
- ffi.set_source("_demo_cffi", """
+ ffibuilder.set_source("_demo_cffi", """
#include <the_event_library.h>
""")
@@ -589,7 +589,7 @@
::
- ffi.set_source("_demo_cffi", """
+ ffibuilder.set_source("_demo_cffi", """
#include <the_event_library.h>
static void my_event_callback(widget_t *, event_t *);
@@ -601,11 +601,11 @@
directly. Here is an example (inefficient in this case, but might be
useful if the logic in ``my_algo()`` is much more complex)::
- ffi.cdef("""
+ ffibuilder.cdef("""
extern "Python" int f(int);
int my_algo(int);
""")
- ffi.set_source("_example_cffi", """
+ ffibuilder.set_source("_example_cffi", """
static int f(int); /* the forward declaration */
static int my_algo(int n) {
@@ -646,10 +646,10 @@
these attributes must be written alongside the function *header*, and
it is fine if the function *implementation* does not repeat them::
- ffi.cdef("""
+ ffibuilder.cdef("""
extern "Python+C" int f(int); /* not static */
""")
- ffi.set_source("_example_cffi", """
+ ffibuilder.set_source("_example_cffi", """
/* the forward declaration, setting a gcc attribute
(this line could also be in some .h file, to be included
both here and in the other C files of the project) */
@@ -805,12 +805,12 @@
import cffi
- ffi = cffi.FFI()
- ffi.cdef("""
+ ffibuilder = cffi.FFI()
+ ffibuilder.cdef("""
int (*python_callback)(int how_many, int *values);
void *const c_callback; /* pass this const ptr to C routines */
""")
- lib = ffi.set_source("_example", """
+ ffibuilder.set_source("_example", """
#include <stdarg.h>
#include <alloca.h>
static int (*python_callback)(int how_many, int *values);
@@ -825,6 +825,7 @@
return python_callback(how_many, values);
}
""")
+ ffibuilder.compile(verbose=True)
.. code-block:: python
@@ -872,7 +873,7 @@
or::
- ffi.cdef("""
+ ffibuilder.cdef("""
struct foo_s {
int (__stdcall *MyFuncPtr)(int, int);
};
More information about the pypy-commit
mailing list