RFR: Add jextract guide [v6]

[Jorn Vernee]

On Mon, 15 Apr 2024 14:04:16 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Not sure... I know what you mean, but knowing how to run the generated code seems fairly important. It seems that that is something someone might want to try out after the first example. Unfortunately, this requires understanding library loading, which is fairly complex.
>> 
>> Also, the comment about feeding jextract the right header file seems pretty important since user may run into errors when running jextract otherwise (we've seen many questions about that, e.g. when someone tries to extract some arbitrary Windows header instead of `Windows.h`).
>> 
>> But also, I realized that this guide may not just be used by first-time readers, but also as a reference by more experienced users, in which case it seems nice to have info about command line flags mostly in one place.
>
> 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 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?

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

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