RFR: Add jextract guide [v12]

[Jorn Vernee]

On Mon, 15 Apr 2024 23:36:30 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Update doc/GUIDE.md
>>   
>>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>
> doc/GUIDE.md line 266:
> 
>> 264: using `-D` on the command line, no accessor will be generated.
>> 265: 
>> 266: ### Structs & Unions
> 
> This section follows an example using a struct. If there's no difference whatsoever compared to a union, this is fine. Otherwise, I will mention in the example where things might differ.

It's exactly the same for both (I'll mention that as well)

> doc/GUIDE.md line 312:
> 
>> 310:     public static MemorySegment reinterpret(MemorySegment addr, long elementCount,
>> 311:             Arena arena, Consumer<MemorySegment> cleanup) { ... } // 6
>> 312: }
> 
> I noticed that some of these methods are `final` and some aren't. Is this on purpose in jextract (why?), or just here?

static methods don't need to be `final`. I think that may be an artifact of some code sharing we do internally.

> doc/GUIDE.md line 739:
> 
>> 737: name is then mapped to a platform dependent name using [`System::mapLibraryName`](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/System.html#mapLibraryName(java.lang.String)).
>> 738: This means, for instance, that on Linux, when specifying `--library mylib`, the bindings will
>> 739: try to load `libmylib.so` using the OS-specific library loading mechanism on Linux, which
> 
> `libmylib.so` -> not `mylib.so`?

No, `mapLibraryName` adds the `lib` prefix on Linux

-------------

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566593004
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566592704
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566593792