RFR: Add guide section about platform-dependent nature of jextract

[Maurizio Cimadamore]

On Wed, 17 Apr 2024 18:38:00 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> The current guide is lacking a discussion about the platform dependent nature of jextract, leaving users to wonder if and when the bindings generated by jextract can be used on different platforms.
> 
> This PR adds a couple of paragraphs to the guide to explain this.
> 
> Note: I've also fixed a typo in the README.

doc/GUIDE.md line 88:

> 86: [Using The Code Generated By Jextract section](#using-the-code-generated-by-jextract)).
> 87: 
> 88: Generally speaking, the code that jextract generates is dependent on the platform on which

Suggestion:

Generally speaking, the bindings generated by jextract depend on the platform on which

doc/GUIDE.md line 94:

> 92: also the section on [pre-processor definitions](#preprocessor-definitions)). Additionally,
> 93: different built in C types can have different formats depending on the platform (for
> 94: example, the `long` type has different formats on Linux and Windows). Both of these are

Maybe we also want to mention padding in structs?

doc/GUIDE.md line 102:

> 100: 
> 101: However, it is also possible for a C library to be written in such a way that it is not
> 102: platform dependent: a so-called _portable_ library. Sharing the bindings generated for a

Perhaps here we might say what moves portable libraries might do - such as use `long long` instead of `long`, or using sized numeric types e.g. `int32`.

doc/GUIDE.md line 104:

> 102: platform dependent: a so-called _portable_ library. Sharing the bindings generated for a
> 103: portable library across different platforms should work without issues. It is typically
> 104: advisable to generate different sets of bindings, once on each platform on which the

Suggestion:

advisable to generate different sets of bindings, one on each platform on which the

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

PR Review Comment: https://git.openjdk.org/jextract/pull/237#discussion_r1569555047
PR Review Comment: https://git.openjdk.org/jextract/pull/237#discussion_r1569554405
PR Review Comment: https://git.openjdk.org/jextract/pull/237#discussion_r1569553123
PR Review Comment: https://git.openjdk.org/jextract/pull/237#discussion_r1569553637