RFR: Add jextract guide

[Maurizio Cimadamore]

On Tue, 9 Apr 2024 17:20:22 GMT, Jorn Vernee <jvernee 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 63:

> 61: Therefore, jextract is intended to be run once, and then for the generated sources to be added to the project.
> 62: Jextract only needs to be run again when the native library, or jextract itself are updated. (This is also
> 63: the workflow that jextract itself uses for talking to the libclang library).

Suggestion:

the workflow that jextract itself follows: jextract depends on the libclang (link?) native library in order to parse C sources).

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?

doc/GUIDE.md line 72:

> 70: library loading mechanism on Linux, which is [`dlopen`](https://man7.org/linux/man-pages/man3/dlopen.3.html).
> 71: This way of loading libraries also relies on OS-specific search mechanisms to find the library file.
> 72: On Linux the search path can be ammended using the `LD_LIBRARY_PATH` environment variable (see the documentation of `dlopen`).

Suggestion:

On Linux the search path can be amended using the `LD_LIBRARY_PATH` environment variable (see the documentation of `dlopen`).

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559150878
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559151912
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559153321