[RFC PATCH liburing v1 0/2] Explain how to build liburing and FFI support

[RFC PATCH liburing v1 0/2] Explain how to build liburing and FFI support

[Ammar Faizi]

From: Ammar Faizi <ammarfaizi2@gnuweeb.org>

Hi Jens,

This is an RFC patchset.

  ## Patch 1
  Tell people how to build liburing.

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

What do you think?

Signed-off-by: Ammar Faizi <ammarfaizi2@gnuweeb.org>
---

Ammar Faizi (2):
  README: Explain how to build liburing
  README: Explain about FFI support

 README | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)


base-commit: 19424b0baa5999918701e1972b901b0937331581
-- 
Ammar Faizi

[RFC PATCH v1 liburing 1/2] README: Explain how to build liburing

[Ammar Faizi]

From: Ammar Faizi <ammarfaizi2@gnuweeb.org>

Tell people how to build liburing.

Signed-off-by: Ammar Faizi <ammarfaizi2@gnuweeb.org>
---
 README | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/README b/README
index 80d2b3d..4dd59f6 100644
--- a/README
+++ b/README
@@ -47,6 +47,30 @@ the kernel io_uring support. Please note that this suite isn't expected to
 pass on older kernels, and may even crash or hang older kernels!
 
 
+Building liburing
+-----------------
+
+    #
+    # Prepare build config (optional).
+    #
+    #  --cc  specifies the C   compiler.
+    #  --cxx speficies the C++ compiler.
+    #
+    ./configure --cc=gcc --cxx=g++;
+
+    #
+    # Build liburing.
+    #
+    make -j$(nproc);
+
+    #
+    # Install liburing (headers, shared/static libs, and manpage).
+    #
+    sudo make install;
+
+See './configure --help' for more information about build config options.
+
+
 License
 -------
 
-- 
Ammar Faizi

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

[Ammar Faizi]

From: Ammar Faizi <ammarfaizi2@gnuweeb.org>

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 <ammarfaizi2@gnuweeb.org>
---
 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.
+
+
 License
 -------
 
-- 
Ammar Faizi

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

[Jens Axboe]

On 1/14/23 2:55?AM, Ammar Faizi wrote:
> From: Ammar Faizi <ammarfaizi2@gnuweeb.org>
> 
> 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 <ammarfaizi2@gnuweeb.org>
> ---
>  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

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

[Jens Axboe]

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.

-- 
Jens Axboe

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

[Christian Mazakas]

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

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

[Jens Axboe]

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?

-- 
Jens Axboe

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

[Ammar Faizi]

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.

-- 
Ammar Faizi