RFR: Add guide section about platform-dependent nature of jextract
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. ------------- Commit messages: - use italic - phrasing - Add notes on platform-dependent nature of jextract Changes: https://git.openjdk.org/jextract/pull/237/files Webrev: https://webrevs.openjdk.org/?repo=jextract&pr=237&range=00 Stats: 22 lines in 2 files changed: 21 ins; 0 del; 1 mod Patch: https://git.openjdk.org/jextract/pull/237.diff Fetch: git fetch https://git.openjdk.org/jextract.git pull/237/head:pull/237 PR: https://git.openjdk.org/jextract/pull/237
On Wed, 17 Apr 2024 18:38:00 GMT, Jorn Vernee <jvernee@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
On Wed, 17 Apr 2024 21:06:04 GMT, Maurizio Cimadamore <mcimadamore@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
The above is to streamline things a bit (optional) ------------- PR Review Comment: https://git.openjdk.org/jextract/pull/237#discussion_r1569555605
On Wed, 17 Apr 2024 21:05:40 GMT, Maurizio Cimadamore <mcimadamore@openjdk.org> wrote:
Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
Apply suggestions from code review
Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore@users.noreply.github.com>
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?
That only really comes into play on ABIs that use a different packing (like the AIX ABI), so it doesn't really seem that important to mention. Any way, the things I mentioned are just a couple of examples. With pre-processor directives a header could really create any kind of platform dependency it wants. ------------- PR Review Comment: https://git.openjdk.org/jextract/pull/237#discussion_r1570680760
On Wed, 17 Apr 2024 21:04:52 GMT, Maurizio Cimadamore <mcimadamore@openjdk.org> wrote:
Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
Add example of portable library practice
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`.
Added this:
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`).
------------- PR Review Comment: https://git.openjdk.org/jextract/pull/237#discussion_r1570691904
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.
Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision: Apply suggestions from code review Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore@users.noreply.github.com> ------------- Changes: - all: https://git.openjdk.org/jextract/pull/237/files - new: https://git.openjdk.org/jextract/pull/237/files/aaddfb65..a5be8cbf Webrevs: - full: https://webrevs.openjdk.org/?repo=jextract&pr=237&range=01 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=237&range=00-01 Stats: 2 lines in 1 file changed: 0 ins; 0 del; 2 mod Patch: https://git.openjdk.org/jextract/pull/237.diff Fetch: git fetch https://git.openjdk.org/jextract.git pull/237/head:pull/237 PR: https://git.openjdk.org/jextract/pull/237
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.
Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision: Add example of portable library practice ------------- Changes: - all: https://git.openjdk.org/jextract/pull/237/files - new: https://git.openjdk.org/jextract/pull/237/files/a5be8cbf..f9f28a4d Webrevs: - full: https://webrevs.openjdk.org/?repo=jextract&pr=237&range=02 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=237&range=01-02 Stats: 8 lines in 1 file changed: 2 ins; 0 del; 6 mod Patch: https://git.openjdk.org/jextract/pull/237.diff Fetch: git fetch https://git.openjdk.org/jextract.git pull/237/head:pull/237 PR: https://git.openjdk.org/jextract/pull/237
On Thu, 18 Apr 2024 13:03:34 GMT, Jorn Vernee <jvernee@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.
Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
Add example of portable library practice
Marked as reviewed by mcimadamore (Reviewer). ------------- PR Review: https://git.openjdk.org/jextract/pull/237#pullrequestreview-2008849848
On Wed, 17 Apr 2024 18:38:00 GMT, Jorn Vernee <jvernee@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.
This pull request has now been integrated. Changeset: 55ab7f4d Author: Jorn Vernee <jvernee@openjdk.org> URL: https://git.openjdk.org/jextract/commit/55ab7f4dbf38e65b18f80be2482fc1baa707... Stats: 24 lines in 2 files changed: 23 ins; 0 del; 1 mod Add guide section about platform-dependent nature of jextract Reviewed-by: mcimadamore ------------- PR: https://git.openjdk.org/jextract/pull/237
participants (2)
-
Jorn Vernee
-
Maurizio Cimadamore