Add guide section about platform-dependent nature of jextract

Reviewed-by: mcimadamore

Author: JornVernee

README.md

@@ -1,6 +1,6 @@
 ## Jextract
 
-`jextract` is a tool which mechanically generates Java bindings from a native library headers. This tools leverages the [clang C API](https://clang.llvm.org/doxygen/group__CINDEX.html) in order to parse the headers associated with a given native library, and the generated Java bindings build upon the [Foreign Function & Memory API](https://openjdk.java.net/jeps/454). The `jextract` tool was originally developed in the context of [Project Panama](https://openjdk.java.net/projects/panama/) (and then made available in the Project Panama [Early Access binaries](https://jdk.java.net/panama/)).
+`jextract` is a tool which mechanically generates Java bindings from native library headers. This tools leverages the [clang C API](https://clang.llvm.org/doxygen/group__CINDEX.html) in order to parse the headers associated with a given native library, and the generated Java bindings build upon the [Foreign Function & Memory API](https://openjdk.java.net/jeps/454). The `jextract` tool was originally developed in the context of [Project Panama](https://openjdk.java.net/projects/panama/) (and then made available in the Project Panama [Early Access binaries](https://jdk.java.net/panama/)).
 
 :bulb: For instruction on how to use the jextract tool, please refer to the guide [here](doc/GUIDE.md).
 

doc/GUIDE.md

@@ -85,6 +85,29 @@ function pointer types, and typedefs of struct or union types result in addition
 being generated. (All of these are discussed in more detail in the
 [Using The Code Generated By Jextract section](#using-the-code-generated-by-jextract)).
 
+Generally speaking, the bindings generated by jextract depend on the platform on which
+jextract is running. For example, when a C header file is processed by the C pre-processor,
+it is possible for code in the header file to detect the current platform using
+pre-processor directives, and expand to a different result based on that platform (see
+also the section on [pre-processor definitions](#preprocessor-definitions)). Additionally,
+different built in C types can have different formats depending on the platform (for
+example, the `long` type has different formats on Linux and Windows). Both of these are
+examples of things that can lead jextract to generate different outputs depending on the
+platform on which it is run. Care should be taken when generating bindings with jextract
+on one platform, and using those bindings on another platform, as the header files may
+contain platform-dependent code that can cause the generated code to misbehave when used
+on another platform.
+
+However, it is also possible for a C library to be written in such a way that it is not
+platform dependent: a so-called _portable_ library. These libraries, for instance, use
+data types that have the same format on all supported platforms (such as `long long`
+instead of `long`, or an explicitly-sized integer type such as `int64_t`). Sharing the
+bindings generated for a portable library across different platforms should work without
+issues. It is typically advisable to generate different sets of bindings, one on each
+platform on which the bindings are intended to be used, and then comparing the generated
+code to make sure that there are no differences between platforms, before sharing a single
+set of bindings between different platforms.
+
 Jextract assumes that the version of a native library that a project uses is relatively stable.
 Therefore, jextract is intended to be run once, and then for the generated sources to be added to the project.
 Jextract only needs to be run again when the native library, or jextract itself are updated.