[RFC,v1,liburing,2/2] README: Explain about FFI support

Commit Message

Ammar Faizi Jan. 14, 2023, 9:55 a.m. UTC

From: Ammar Faizi <[e-mail]>

Tell people that they should use the FFI variants when they can't use
'static inline' functions defined in liburing.h.

Signed-off-by: Ammar Faizi <[e-mail]>
---
 README | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

Comments

Jens Axboe Jan. 14, 2023, 5:19 p.m. UTC | #1

On 1/14/23 2:55?AM, Ammar Faizi wrote:
> From: Ammar Faizi <[e-mail]>
> 
> Tell people that they should use the FFI variants when they can't use
> 'static inline' functions defined in liburing.h.
> 
> Signed-off-by: Ammar Faizi <[e-mail]>
> ---
>  README | 19 +++++++++++++++++++
>  1 file changed, 19 insertions(+)
> 
> diff --git a/README b/README
> index 4dd59f6..7babb3b 100644
> --- a/README
> +++ b/README
> @@ -71,6 +71,25 @@ Building liburing
>  See './configure --help' for more information about build config options.
>  
>  
> +FFI support
> +-----------
> +
> +By default, the build results in 4 lib files:
> +
> +    2 shared libs:
> +
> +        liburing.so
> +        liburing-ffi.so
> +
> +    2 static libs:
> +
> +        liburing.a
> +        liburing-ffi.a
> +
> +For languages and applications that can't use 'static inline' functions in
> +liburing.h should use the FFI variants.

Maybe include something on why they can't use them? And that sentence would
be better as:

Languages and applications that can't use 'static inline' functions in
liburing.h should use the FFI variants.

Jens Axboe Jan. 15, 2023, 6:18 p.m. UTC | #2

On 1/14/23 9:25?PM, Christian Mazakas wrote:
> For some historical context, this feature came about from trying to
> consume liburing from Rust. liburing is such a powerful library and
> it's hard to replace so a dependency on it is reasonable for
> applications wishing to leverage io_uring without developers being
> systems-level experts.
> 
> For languages that can't parse C headers, liburing-ffi saves quite a
> bit of effort in terms of bringing liburing itself to the application
> because it gives consumers a defined set of symbols in the binaries to
> link against.

Oh I know why it was done and why it's there, this is for the
purpose of the README addition. I think it should be a bit more
verbose and explain that.

Christian Mazakas Jan. 16, 2023, 4:18 a.m. UTC | #3

Hmm, how about something more like this:

+Because liburing's main public interface lives entirely in liburing.h
as `static inline`
+functions, users wishing to consume liburing purely as a binary
dependency should
+link against liburing-ffi. liburing-ffi contains definitions for
every `static inline` function
+in liburing.h.

- Christian

Jens Axboe Jan. 16, 2023, 1:44 p.m. UTC | #4

On 1/15/23 9:18 PM, Christian Mazakas wrote:
> Hmm, how about something more like this:
> 
> +Because liburing's main public interface lives entirely in liburing.h
> as `static inline`
> +functions, users wishing to consume liburing purely as a binary
> dependency should
> +link against liburing-ffi. liburing-ffi contains definitions for
> every `static inline` function
> +in liburing.h.

This is great - Ammar, can you incorporate that when you respin the
patchset?

Ammar Faizi Jan. 16, 2023, 1:54 p.m. UTC | #5

On Mon, Jan 16, 2023 at 06:44:40AM -0700, Jens Axboe wrote:
> This is great - Ammar, can you incorporate that when you respin the
> patchset?

Roger that. Will respin the patchset with that incorporated.

Patch

diff --git a/README b/README
index 4dd59f6..7babb3b 100644
--- a/README
+++ b/README
@@ -71,6 +71,25 @@  Building liburing
 See './configure --help' for more information about build config options.
 
 
+FFI support
+-----------
+
+By default, the build results in 4 lib files:
+
+    2 shared libs:
+
+        liburing.so
+        liburing-ffi.so
+
+    2 static libs:
+
+        liburing.a
+        liburing-ffi.a
+
+For languages and applications that can't use 'static inline' functions in
+liburing.h should use the FFI variants.
+
+
 License
 -------