[Teem-commit] SF.net SVN: teem:[7251] teem/trunk/python/cffi/README.md

[<kin...@us...>]

Revision: 7251
          http://sourceforge.net/p/teem/code/7251
Author:   kindlmann
Date:     2025-04-14 10:53:14 +0000 (Mon, 14 Apr 2025)
Log Message:
-----------
tweaks2 as GLK revisits this and gets it working on new laptop

Modified Paths:
--------------
    teem/trunk/python/cffi/README.md

Modified: teem/trunk/python/cffi/README.md
===================================================================
--- teem/trunk/python/cffi/README.md	2025-04-14 10:50:44 UTC (rev 7250)
+++ teem/trunk/python/cffi/README.md	2025-04-14 10:53:14 UTC (rev 7251)
@@ -19,7 +19,7 @@
 - `teem.py` (distributed with Teem source): enables "import teem" from python3, and provides access to the entire Teem API, with some added benefits (mainly `biff` errors turning into Python exceptions). `teem.py` is generated by `build_teem.py` in its final "wrap" step. At runtime,`teem.py` relies on an `import _teem` which dynamically loads and links in:
 - `_teem.cpython-`_platformspecifics_`.so` (created by user, because it is specific to the local OS and the local version of Python): This platform-specific shared library is the bridge between Python and the symbols in `$TEEM_INSTALL/lib/libteem`. Linking regular C code with `libteem` requires declarations from the .h headers in `$TEEM_INSTALL/include/teem`, but the work of describing the Teem API to CFFI, so as to mirror it all in Python, is done by:
 - `cdef/cdef_air.h`, `cdef/cdef_biff.h`, `cdef/cdef_nrrd.h`, etc (distributed with Teem source): these are restatements of the API of each library in Teem in a form digestable to the meagre C header parser inside `cffi.FFI()`: basically removing all pre-processor logic and all `#define` macros, keeping only the `#define`s around integers (which can be parsed). Some subset of these are read by `Tffi.cdef()` in `exult.py` to tell CFFI what bridge code to generate when creating the extension module. Including these files in the Teem source (as opposed to requiring users to regenerate them) may not be wise, but they are there to be used as part of creating extension module for other non-Teem libraries.
-- `exult.py` (distributed with Teem source) is CFFI **EX**tension module **U**tilities for **L**ibraries depending on **T**eem, which arose with the recognition that knowledge of Teem's organization and contents matter for two things: compiling extension modules that depend on Teem (or are Teem), and wrapping those extension modules in Pythonic ways. `exult.py` defines a `Tffi` object is used to compile extension modules (via its `.cdef()`, `.set_source()`, and `.compile()` methods) and then generate a Python wrapper around the extension module (the `Tffi.wrap()` method). `exult.py` has become home for functionality that started in an earlier version of `teem.py` (such as knowledge of the inter-dependencies of Teem libraries)
+- `exult.py` (distributed with Teem source) is CFFI **EX**tension module **U**tilities for **L**ibraries depending on **T**eem, which arose with the recognition that knowledge of Teem's organization and contents matter for two distinct but connected steps: compiling extension modules that depend on Teem (or are Teem), and wrapping those extension modules in Pythonic ways. `exult.py` defines a `Tffi` object is used to compile extension modules (via its `.cdef()`, `.set_source()`, and `.compile()` methods) and then generate a Python wrapper around the extension module (the `Tffi.wrap()` method). `exult.py` has become home for functionality that started in an earlier version of `teem.py` (such as knowledge of the inter-dependencies of Teem libraries)
 - `lliibb.py` (distributed with Teem source) is the template for all the Python wrappers (around extension modules) that `exult.py` can generate, including `teem.py`. No python code will ever "`import lliibb`"; the text of this is transformed by `exult.py`'s `Tffi.wrap()` to generate things like `teem.py`. `lliibb.py` is the new home for functionality (such as the `Tenum` python wrapper for an airEnum) that started in an earlier version of `build_teem.py`. The biggest text transformation that `Tffi.wrap()` does is to inject a Python dictionary summarizing which C functions use `biff`, and how to interpret their return values as errors.
 - `build_teem.py` (distributed with Teem source, run by user): Running `python3 build_teem.py -gch $TEEM_INSTALL` does a lot of fragile hacking on the headers in `$TEEM_INSTALL/include/teem` to produce restatement of Teem library APIs in `cdef/cdef_*.h`. Without the `-gch` option, `python3 build_teem.py $TEEM_INSTALL` will (with help from class `Tffi` in `exult.py`) produce `_teem.c` and compile it to make the `_teem.cpython....so` shared object (above). Whether `$TEEM_INSTALL` includes the "experimental" Teem libraries will determine the contents of `_teem.c`, which why it is not distributed with the Teem source.
 - `biffdata/*.csv`: these are a repackaging of the `/* Biff: */` annotations of the source code in `$TEEM_SRC/src/*/*.c`, which describe what different return values from a Teem C function indicates that the function has used `biff` to describe an error. The `biffdata/*.csv` files are read in by `exult.py`'s `Tffi.wrap()` to generate a Python dictionary `_BIFF_DICT` that `teem.py` (or other wrapper) uses to generate Exceptions upon errors.

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.