RFR: Add jextract guide [v6]

[Maurizio Cimadamore]

On Mon, 15 Apr 2024 14:55:44 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> While it's true that knowing which header to extract is important, I think having a whole section on "preprocessor definitions" feels like having a very cornery section in a place where in reality you want something more general. E.g. extracting windows.h is tricky, because of order dependencies, but I'm not sure the user needs to be aware of -D here. Just mentioning that headers are complex beasts and can depend on each other in unpredictable ways (and refer to the doc of the library that needs to be extracted) should be good enough guidance at this point.
>> 
>> As for library loading I'm not sure... again, yes, we probably need to say something like "you need to ensure the library you want to call is loaded first" - but I'm not sure we need the full shebang of library loading options. In other places you added references to stuff that is further expanded upon in later sections - e.g. 
>> 
>> 
>> Besides these options, it is also possible to filter the output of jextract using one of the --include-XXX options that jextract has. See the section on [filtering](https://github.com/JornVernee/jextract/blob/Guide/doc/GUIDE.md#filtering) for a more detailed overview.
>> 
>> 
>> Seems like something similar is required here.
>
> 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.

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

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