From 5e9954c76ea221217d34399fa853849c290b7854 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Alexis=20Laferri=C3=A8re?= Date: Fri, 8 May 2015 10:05:12 -0400 Subject: [PATCH] src/ffi: document the differences between the light and full FFI MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Alexis Laferrière --- src/ffi/ffi.nit | 25 ++++++++++++++++++++++--- src/ffi/light_ffi.nit | 19 ++++++++++++++++--- 2 files changed, 38 insertions(+), 6 deletions(-) diff --git a/src/ffi/ffi.nit b/src/ffi/ffi.nit index 15e1dac..e58d32a 100644 --- a/src/ffi/ffi.nit +++ b/src/ffi/ffi.nit @@ -14,9 +14,28 @@ # See the License for the specific language governing permissions and # limitations under the License. -# FFI concers common between the compilers and the interpreter. -# Offers services to compile modules using foreign code. Mainly allows -# to wrap foreign code in Nit methods. +# Full FFI support, independent of the compiler +# +# The full FFI support all the features of the light FFI and more: +# +# * More foreign languages: **C++, Java and Objective-C**. +# * **Callbacks** to Nit from foreign codes. +# The callbacks are declared in Nit using the `import` annotation on extern methods. +# They are then generated on demand for the target foreign language. +# * **Static Nit types** in C for precise typing and static typing errors in C. +# * **Propagating public code blocks** at the module level (C Header). +# This allows to use extern classes in foreign code in other modules +# without having to import the related headers. +# This is optional in C as it is easy to find the correct importation. +# However it is important in Java and other complex FFIs. +# * **Reference pinning** of Nit objects from foreign code. +# This ensure that objects referenced from foreign code are not liberated by the GC. +# * FFI **annotations**: +# * `cflags`, `ldflags` and `cppflags` pass arguments to the C and C++ +# compilers and linker. +# * `pkgconfig` calls the `pkg-config` program to get the arguments +# to pass to the C copiler and linker. +# * `extra_java_files` adds Java source file to the compilation chain. module ffi import modelbuilder diff --git a/src/ffi/light_ffi.nit b/src/ffi/light_ffi.nit index b099681..2245a92 100644 --- a/src/ffi/light_ffi.nit +++ b/src/ffi/light_ffi.nit @@ -14,9 +14,22 @@ # See the License for the specific language governing permissions and # limitations under the License. -# FFI concers common between the compilers and the interpreter. -# Offers services to compile modules using foreign code. Mainly allows -# to wrap foreign code in Nit methods. +# Light FFI support, independent of the compiler +# +# The light FFI offers only basic FFI features: +# +# * **Extern methods** implemented in C, nested within the Nit code. +# The body of these method is copied directly to the generated C files for compilation. +# Also supports extern `new` factories. +# * Module level **C code blocks**, both "C Body" (the default) and "C Header". +# They will be copied to the beginning of the generated C files. +# * Automatic transformation of Nit **primitive types** from/to their equivalent in C. +# * **Extern classes** to create a Nit class around a C pointer. +# Allows to specify the equivalent C type of the Nit extern class. +# +# These limited features should be easy to implement in new/alternative engines +# to quickly achieve a bootstrap. For this reason, core features of the Nit +# standard library should be limited to use the light FFI. module light_ffi import modelbuilder -- 1.7.9.5