Provide user docs

[ChristianSchwarz]

As a potential user of JNR i would like to start with some documentation, but i can't find any!
Here is what i would like to see:

• a "Get started" guide
• cookbook with mapping samples of C/C++ functions, callbacks, pointer, stucts, datatype conversion and so on to JNR/Java
• JavaDocs
• Design guidlines
• comparison to JNI and JNA with samples
• a link to a user Forum or google group
• tutorial how to setup a build enviroment for Win, Mac, Linux ..
• you name it

JNA has some good documentationfor a reference -> http://twall.github.io/jna/4.1.0/overview-summary.html

[aaime]

I was looking for the same. On one side I see this is meant to be eventually merged into official Java, but the lack of documentation today makes one think it's for the moment just a project meant to support JRuby (which is fine btw).

[headius]

There is at least JavaDocs and some other maven noise generated at http://jnr.github.io/jnr-ffi but it doesn't really include user documentation or good examples. This is a known issue and I agree we need to do better. Please help!

[coding-jj]

Could you summarize links to existing documents, examples, presentations , etc. in the wiki of the project. I stumbled across jnr last week while searching for jna details and now I switched jnr and getting started with complex function calls is very hard. The getpid example is very simple.

[konstantin-krasheninnikov-ullink]

Hello, it would be nice to know how JNR supported platforms correlate to Java's "os.arch" and "os.name." Also an explanation of project dependencies would be quite useful to make an educated decision when choosing a library or packaging it with a product. Thanks in advance.

P.S. I see there's http://www.oracle.com/technetwork/java/jvmls2013nutter-2013526.pdf
..as well as http://jnr.github.io/jnr-ffi/dependencies.html. Maybe those can be linked from README.md

[Kaiser1989]

Using Rust with C-Api for cross language support. But adding Java ffi interface is nearly impossible without documentation. This lead us to stick with JNI just because of documenation lack... sad

[headius]

@Kaiser1989 Yeah I agree it is sad. This is a great library that people don't know about.

We have a single page in the wiki with some example code, and there's the https://github.com/jnr/jnr-ffi-examples repository that has more examples. There's also the upstream JNR projects like jnr-posix, jnr-enxio, jnr-unixsocket, and jnr-process that could be mined for examples. Perhaps we can work together to improve the wiki, and ideally start publishing some docs at http://jnrproject.org/ to resolve this issue?

[Kaiser1989]

Tbh I switched to "BridJ" which provides pretty nice java docs and easy to use Pointer handling (Deref, pointer iteration, offsets, allocation, release, even auto Java generation code with "jnaerator"). Von meinem Mobiltelefon gesendet

…

________________________________ From: Charles Oliver Nutter <notifications@github.com> Sent: Monday, October 26, 2020 9:42:59 PM To: jnr/jnr-ffi <jnr-ffi@noreply.github.com> Cc: Philipp Kaiser <philippxkaiser@googlemail.com>; Mention <mention@noreply.github.com> Subject: Re: [jnr/jnr-ffi] Provide user docs (#42) @Kaiser1989<https://github.com/Kaiser1989> Yeah I agree it is sad. This is a great library that people don't know about. We have a single page in the wiki with some example code, and there's the https://github.com/jnr/jnr-ffi-examples repository that has more examples. There's also the upstream JNR projects like jnr-posix, jnr-enxio, jnr-unixsocket, and jnr-process that could be mined for examples. Perhaps we can work together to improve the wiki, and ideally start publishing some docs at http://jnrproject.org/ to resolve this issue? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<#42 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AC4S2LOMUXD2KLICA7FPB6LSMXNNHANCNFSM4BEAXIDQ>.

[headius]

@Kaiser1989 BridJ looks nice, but seems to be unmaintained (assuming the URL below is the right place)?

https://github.com/nativelibs4java/BridJ

I believe all the features you mention are supported by jnr-ffi, except for the generator. That would be a great project to convert to jnr-ffi.

Of course the ultimate solution will eventually be to utilize Project Panama and I'd love for someone to give that a shot too.

[Kaiser1989]

I believe all the features you mention are supported by jnr-ffi, except for the generator

I'm sure it does, but there is really no way to get into this project without any information. See, i created the whole C-Api-Java-Interface for our company project with BridJ, just from javadocs within 5 hours.

I first tried to use jnr-ffi and stuck reading array data from raw-C-pointer for about 3 hours... Information about releasing pointer or memory is completely missing.

I like java's ffi stuff, as it moves the complete connection out of native projects (there really shouldn't be any java related functions). But this project is currently unusable. The examples are also unusable .... They are way too generic.

TBH, i don't have time and effort to get into this project. I hope someone gets this done. A maintained, good documented java ffi project is really needed.

But i will write down the biggest pains starting with jnr-ffi:

• What is the Runtime? Why do i have to use it, why isn't it handled internally
• Why does Structs need Runtime as constructor? (Is there already a memory allocation, then when it gets released?)
• Why are inner structs so complicated (you need to spread the runtime)
• How can arrays be read from raw pointers (not talking about primitives, but structs)
• How can arrays be created in Java (not talking about primitives, but structs)
• How do i get Pointer to an array (pointer from native code, often used as ptr* and len)
• When is memory allocated (when creating the object?)
• When is memory released (can it be called manually? Are native pointers release automatically? Hope not)
• What is DelegatingMemoryIO? How is it used? What kind of memory is there, (found something like shared, ...)
• How to deref a pointer and get it's struct? (is this working with inner structs?)
• How are nested structs working? (are they a single memory block?)
• Conversion of native array to Java List

What i like when using BridJ:
Structs are just for knowing size, everything is else is done with Pointer:

// Following is some sort of pseudo code using BridJ (just want to show the concept)

// struct
Pointer<MyClass> ptr = Pointer.allocate(MyClass.class);
// do some stuff like deref, change value, ...
ptr.get().value(500);
ptr.release();

// arrays are pretty easy
Pointer ptr = Pointer.allocateArray(MyClass.class, 10);
ptr.get(4).value(500);
ptr.release();

// reinterpret type? why not
Pointer<MyClass> ptr = otherPtr.getAsType(MyClass.class);

You see, it's absolutly clear, when memory is allocated and when it's freed.

Hope this will help.
Best regards

[headius]

@Kaiser1989 This is a great list, thank you! Hopefully I will have time to circle back to try to put together a better baseline documentation, as well as a FAQ for the key questions in your list.

One difference with structs in jnr-ffi is that they are explicitly tied to a Java field layout, so that the type conversions, endianness, etc are all handled for you. You can certainly just allocate memory and get a Pointer and access offsets from that pointer as in your example.

[basshelal]

@headius
I think this is something that we should put some more focus and priority on and I am willing to help as much as I can in this regard.

I think something akin to JNA's wiki style documentation found here is a great starting point.

I personally think that it is of equal, if not more, importance that the code has better JavaDocs as well, this way deep debugging can be made easier (in addition to maintenance of course), for example in the scenario that you are using JNR incorrectly, you can at least figure out what is being called internally and what it does, something I often do when dealing with complex APIs. JNA is also better at this and we can learn from them as well in this regard.

I will take it upon myself personally to do as much as I can with the knowledge I have and I can find in JNR.

[headius]

I have merged in the great starting documentation from @basshelal! That might constitute a resolution for this issue, but there's certainly more to be done. A good task going forward would be to add more examples to https://github.com/jnr/jnr-ffi-examples and make sure those examples are explained in the docs. We also have had a number of issues that are really requests for documentation; we could audit those to fill in more content.

@ChristianSchwarz Please have a look at the newly-added docs and feel free to submit improvements via PR!