RFR: Add jextract guide

[Jorn Vernee]

On Wed, 10 Apr 2024 09:32:13 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> doc/GUIDE.md line 29:
> 
>> 27: library called `mylib` stored at `/path/to/mylib` that has a directory `/path/to/mylib/include`
>> 28: with all the header files. And let's say that we have a shell open in the root directory
>> 29: of the Java project we're working on, which has an `src` source directory corresponding to
> 
> Suggestion:
> 
> of the Java project we're working on, which has a `src` source directory corresponding to

It depends on how you read `src`. If you read S R C, then `an` is appropriate.

> doc/GUIDE.md line 68:
> 
>> 66: 
>> 67: When using the `--library <libspec>` option, the generated code internally uses [`SymbolLookup::libraryLookup`](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/foreign/SymbolLookup.html#libraryLookup(java.nio.file.Path,java.lang.foreign.Arena))
>> 68: to load libraries specified by `<libspec>`, after potentially mapping the name of the library 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)).
> 
> potentially? Are there cases where mapping a library name is a no-op?

The `<libspec>` might be a path (using `:`), in which case we don't  do any mapping, right? I don't mind removing the `potentially` here though.

> doc/GUIDE.md line 257:
> 
>> 255: 
>> 256: Not all types of macros are supported though. Only macros that have a primitive numerical
>> 257: value, a string, or a pointer type are supported. Most notably, function-like macros are
> 
> Several people wonder what to do when dealing with a library that is heavy in its use of function-like macros. There's two strategies here - the first is to replicate the code in the function-like macro in Java, using FFM. The second is to create a small C library which turns the function-like macro into a proper function, so that it can be used from FFM. Not sure we want to add this detail here (or maybe in an appendix).

I think something like that is good to add here. This guide is meant to be comprehensive. If we think some information is useful in the use of jextract, let's add it to the guide.

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559449360
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559446730
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559444213