RFR: Add jextract guide [v6]

[Jorn Vernee]

On Mon, 15 Apr 2024 15:05:22 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Still not sure. The section on pre-processor definitions is already fairly small, and in some rare cases, `-D` may be required for extraction to work as well. Do we really want to put ~half this section elsewhere? It seems this information is relevant to 'Running Jextract' as well.
>> 
>> For library loading, a user needs to know what happens to the string they pass to `--library`, which requires understanding the distinction between library names/paths, and the fact that the user needs to set `LD_LIBRARY_PATH`/`DYLD_LIBRARY_PATH`/`PATH`. Even for someone who's experienced with native library loading, that seems like important information? (i.e. because it's not clear how jextract handles this)
>> 
>> I think in both cases, we would end up splitting just part of the information into a separate section. Even if not ideal, I think it's better to keep all the info together. So, if we can't get away with moving these sections out-of-line completely, which I don't think we can, I'm inclined to leave things as they are in this area.
>> 
>> Maybe we can improve the situation by having a very basic hello world example up front?
>
> IMHO is not about moving "half sections", but about writing a section that is correct for the purpose and context in which it appears in the document. We seem to have two requirements for users getting started with jextract:
> * explain that the header on which it is run matters (this can literally be one sentence)
> * explain that libraries must be loaded (I think here we can get away by providing something that works in the 80% use cases, plus some comment on LD_LIBRARY_PATH, and refer everything else to a more specialized section. E.g. I don't think here we should be talking about different lookups, in which orders symbols are looked up etc.).
> 
> This way you can have a document that serves both "green" developers and more experienced one (the latter will want to keep going after the section illustrating how to use bindings). At least, IMHO.

I gave this a try in the latest version. Still not sure which one is better, but I don't mind either way. I put all the sections after the examples in an 'Advanced' section as well.

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565981693