From jvernee at openjdk.org  Tue Apr  2 15:09:10 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 2 Apr 2024 15:09:10 GMT
Subject: RFR: Fix javadoc generation and add check to testing suite [v2]
In-Reply-To: <PUtrObsaIobNIP7LGBmET-kcBDQbcgLjLfhQk6h_srg=.13ad0efd-6f07-487a-9a40-619c925d08dc@github.com>
References: <vJJs5rYzBMLmMLjuNUg2s8WvTC8pmtI59gIX2zo7q0k=.ba6f7936-a20d-4002-8a23-933e133dd87c@github.com>
 <PUtrObsaIobNIP7LGBmET-kcBDQbcgLjLfhQk6h_srg=.13ad0efd-6f07-487a-9a40-619c925d08dc@github.com>
Message-ID: <LuL_FueOmGXEVpwJ4rOzRHEiOt3PMv4KPyhIRXGc43Q=.72b0f0eb-5a39-4748-a820-879418c4d4ec@github.com>

On Thu, 28 Mar 2024 12:07:56 GMT, James Yuzawa <duke at openjdk.org> wrote:

>> Motivation: There is bad javadoc being generated. This fixes that and also adds a check to the testing suite to make sure it does not happen again.
>> 
>> Notes: I branched off of jdk22 branch since I would like such fixes to make their way into the jdk22 branch. Please let me know if there is a different base or head I should use.
>
> James Yuzawa has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Fix javadoc generation and add check to testing suite
>   
>   Motivation: There is bad javadoc being generated. This fixes that and also adds a check to the testing suite to make sure it does not happen again.

FYI, when you're ready for this to be merged, just type `/integrate`

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

PR Comment: https://git.openjdk.org/jextract/pull/227#issuecomment-2032306826

From jvernee at openjdk.org  Tue Apr  2 15:12:22 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 2 Apr 2024 15:12:22 GMT
Subject: RFR: 7903704: Expose addresses of native functions
Message-ID: <0ntxByd7k8donsRMPAXQQciJJjRvPbYllQwJLMCmLMk=.c02fdb20-d081-4ef1-b295-6cb91998c437@github.com>

Add accessors for the address of a native function. This follows the jextract principle to expose all the information it has as well.

The address is useful in cases where a user needs to pass the address of a native function to be used as a callback by another (higher-order) native function.

Note: while working on this I noticed that the `TestUtils` file was not being rebuilt when dependent tests were running. Many tests depend on this file to compile generated source code for instance. I've added the needed `@build` tags, and `lib.build` property (the latter only works for the tests under `TestNG.dirs`).

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

Commit messages:
 - expose function addresses
 - Add @build testlib.TestUtils

Changes: https://git.openjdk.org/jextract/pull/228/files
  Webrev: https://webrevs.openjdk.org/?repo=jextract&pr=228&range=00
  Issue: https://bugs.openjdk.org/browse/CODETOOLS-7903704
  Stats: 176 lines in 47 files changed: 169 ins; 1 del; 6 mod
  Patch: https://git.openjdk.org/jextract/pull/228.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/228/head:pull/228

PR: https://git.openjdk.org/jextract/pull/228

From duke at openjdk.org  Tue Apr  2 16:04:13 2024
From: duke at openjdk.org (James Yuzawa)
Date: Tue, 2 Apr 2024 16:04:13 GMT
Subject: Integrated: Fix javadoc generation and add check to testing suite
In-Reply-To: <vJJs5rYzBMLmMLjuNUg2s8WvTC8pmtI59gIX2zo7q0k=.ba6f7936-a20d-4002-8a23-933e133dd87c@github.com>
References: <vJJs5rYzBMLmMLjuNUg2s8WvTC8pmtI59gIX2zo7q0k=.ba6f7936-a20d-4002-8a23-933e133dd87c@github.com>
Message-ID: <6yjE0I5xKdxxu-6At8mxddG4N6PPp85yrIFCYbTQeeU=.946cd5c5-c531-402c-9062-d08ab1d3cd0c@github.com>

On Thu, 28 Mar 2024 01:23:47 GMT, James Yuzawa <duke at openjdk.org> wrote:

> Motivation: There is bad javadoc being generated. This fixes that and also adds a check to the testing suite to make sure it does not happen again.
> 
> Notes: I branched off of jdk22 branch since I would like such fixes to make their way into the jdk22 branch. Please let me know if there is a different base or head I should use.

This pull request has now been integrated.

Changeset: c24224e0
Author:    James Yuzawa <jtyuzawa at gmail.com>
Committer: Jorn Vernee <jvernee at openjdk.org>
URL:       https://git.openjdk.org/jextract/commit/c24224e09ef81f581ec6948e5781b35b8453b682
Stats:     31 lines in 9 files changed: 15 ins; 0 del; 16 mod

Fix javadoc generation and add check to testing suite

Reviewed-by: jvernee

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

PR: https://git.openjdk.org/jextract/pull/227

From Klaus.Malorny at knipp.de  Thu Apr  4 14:00:20 2024
From: Klaus.Malorny at knipp.de (Klaus Malorny)
Date: Thu, 4 Apr 2024 16:00:20 +0200
Subject: "#define" constants as methods
Message-ID: <16b17e21-2220-482f-89e7-da9c4818a3d9@knipp.de>


Hi,

I have two projects which currently use JNI and which need to be 
migrated eventually, so I started playing around with Java 22's foreign 
package and the jextract code generator (Build 22-jextract+3-13). What 
puzzles me so far is the fact that constants are generated as methods 
(which actually use static private member variables with the same name). 
This seems to be cumbersome, especially if they are error codes like in 
my case and I want to use them in a switch statement. Maybe there is a 
reasoning behind it, but I can't imagine it ;-)

Besides this, another (dumb) question: How will the tool be finally 
published? Will it become part of the JDK?

Regards,
Klaus


From jorn.vernee at oracle.com  Thu Apr  4 18:38:56 2024
From: jorn.vernee at oracle.com (Jorn Vernee)
Date: Thu, 4 Apr 2024 20:38:56 +0200
Subject: "#define" constants as methods
In-Reply-To: <16b17e21-2220-482f-89e7-da9c4818a3d9@knipp.de>
References: <16b17e21-2220-482f-89e7-da9c4818a3d9@knipp.de>
Message-ID: <3128f4eb-8199-47aa-a0bd-d7a618031eda@oracle.com>

Hello,

For string constants we have to allocate and copy memory, so we defer 
the initialization of those. For that to work, at least string constants 
need to be exposed as methods. Historically we had a different 
translation strategy for constants that also required them to be exposed 
as methods, and I think we kept the methods for all types of constants 
mostly out of consistency.

 > This seems to be cumbersome, especially if they are error codes like 
in my case and I want to use them in a switch statement.

This is a good point. The result of a method call can not be used as a 
case label in a switch. We could potentially change jextract to just 
expose string constants using methods, and use fields for the others. 
This would be inconsistent, but I think better, since it allows 
constants to be used as switch case labels. I suspect Maurizio will want 
to weigh in on this as well.

 > How will the tool be finally published? Will it become part of the JDK?

At least for the foreseeable future it will be kept as a separate tool, 
and published through jdk.java.net

Jorn

On 04/04/2024 16:00, Klaus Malorny wrote:
>
> Hi,
>
> I have two projects which currently use JNI and which need to be 
> migrated eventually, so I started playing around with Java 22's 
> foreign package and the jextract code generator (Build 
> 22-jextract+3-13). What puzzles me so far is the fact that constants 
> are generated as methods (which actually use static private member 
> variables with the same name). This seems to be cumbersome, especially 
> if they are error codes like in my case and I want to use them in a 
> switch statement. Maybe there is a reasoning behind it, but I can't 
> imagine it ;-)
>
> Besides this, another (dumb) question: How will the tool be finally 
> published? Will it become part of the JDK?
>
> Regards,
> Klaus
>

From Klaus.Malorny at knipp.de  Fri Apr  5 07:15:11 2024
From: Klaus.Malorny at knipp.de (Klaus Malorny)
Date: Fri, 5 Apr 2024 09:15:11 +0200
Subject: "#define" constants as methods
In-Reply-To: <3128f4eb-8199-47aa-a0bd-d7a618031eda@oracle.com>
References: <16b17e21-2220-482f-89e7-da9c4818a3d9@knipp.de>
 <3128f4eb-8199-47aa-a0bd-d7a618031eda@oracle.com>
Message-ID: <64d4d240-b9a2-4cb8-a042-63da21537cda@knipp.de>

On 04.04.24 20:38, Jorn Vernee wrote:
> Hello,
> 
> For string constants we have to allocate and copy memory, so we defer 
> the initialization of those. For that to work, at least string constants 
> need to be exposed as methods. Historically we had a different 
> translation strategy for constants that also required them to be exposed 
> as methods, and I think we kept the methods for all types of constants 
> mostly out of consistency.
> 
>  [...]

> Jorn
> 
Hi Jorn,

thanks for the explanation. This makes sense. API consistency is surely 
a valid and valuable argument and my "switch" problem is surely a rather 
seldom one. I did not realize that (complex) constants will be 
represented in their C-style form.

Regards,
Klaus


From maurizio.cimadamore at oracle.com  Fri Apr  5 08:54:34 2024
From: maurizio.cimadamore at oracle.com (Maurizio Cimadamore)
Date: Fri, 5 Apr 2024 09:54:34 +0100
Subject: "#define" constants as methods
In-Reply-To: <3128f4eb-8199-47aa-a0bd-d7a618031eda@oracle.com>
References: <16b17e21-2220-482f-89e7-da9c4818a3d9@knipp.de>
 <3128f4eb-8199-47aa-a0bd-d7a618031eda@oracle.com>
Message-ID: <ce968808-e67e-45f7-b3d6-fef216aa8b42@oracle.com>

Hi

On 04/04/2024 19:38, Jorn Vernee wrote:
> This is a good point. The result of a method call can not be used as a 
> case label in a switch. We could potentially change jextract to just 
> expose string constants using methods, and use fields for the others. 
> This would be inconsistent, but I think better, since it allows 
> constants to be used as switch case labels. I suspect Maurizio will 
> want to weigh in on this as well. 

Unfortunately this is a case where the language puts us in a difficult 
corner - for a value to be usable in a switch label it must be a 
constant expression, and constant expressions include a very limited 
subset of the Java language (including static final fields whose 
initializer is a constant expression).

This creates a tension between usabilty (I think it's natural to want to 
switch on constant values!) and laziness (a constant value must be 
evaluated eagerly, when the class containing the constant field is 
initialized). Given the high number of constants in header classes, we 
preferred laziness (for the reasons Jorn mentions, as there are some 
constants that require some non-trivial setup).

I believe there is also an element of uniformity - e.g. wanting to 
generate similar code for _all_ defined macro constants, rather than 
generating different code based on the constant type. While generating 
different code is definitively possible, we should also be mindful that 
using different codegen strategies for different constant kinds might 
also be confusing on its own.

One possibility I considered at some point was to _not_ convert C 
strings to memory segment constants, and leave them as Java Strings (and 
leave conversion to the user). Then all constants would be of the 
"simple kind". But I'm afraid this would be harsh on string-heavy libraries.

Maurizio


From mcimadamore at openjdk.org  Fri Apr  5 08:59:24 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Fri, 5 Apr 2024 08:59:24 GMT
Subject: RFR: 7903704: Expose addresses of native functions
In-Reply-To: <0ntxByd7k8donsRMPAXQQciJJjRvPbYllQwJLMCmLMk=.c02fdb20-d081-4ef1-b295-6cb91998c437@github.com>
References: <0ntxByd7k8donsRMPAXQQciJJjRvPbYllQwJLMCmLMk=.c02fdb20-d081-4ef1-b295-6cb91998c437@github.com>
Message-ID: <Zth4PFg2gUIcevfExa5WzdqcH7OVL_mEhWyBg68tdJQ=.5d52ed94-10a6-46e4-a03c-50338ee43792@github.com>

On Tue, 2 Apr 2024 15:08:48 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Add accessors for the address of a native function. This follows the jextract principle of exposing all the information that it has.
> 
> The address is useful in cases where a user needs to pass the address of a native function to be used as a callback by another (higher-order) native function.
> 
> Note: while working on this I noticed that the `TestUtils` file was not being rebuilt when dependent tests were running. Many tests depend on this file to compile generated source code for instance. I've added the needed `@build` tags, and `lib.build` property (the latter only works for the tests under `TestNG.dirs`).

Very nice!

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

Marked as reviewed by mcimadamore (Reviewer).

PR Review: https://git.openjdk.org/jextract/pull/228#pullrequestreview-1982394979

From jvernee at openjdk.org  Fri Apr  5 10:36:38 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Fri, 5 Apr 2024 10:36:38 GMT
Subject: RFR: 7903704: Expose addresses of native functions [v2]
In-Reply-To: <0ntxByd7k8donsRMPAXQQciJJjRvPbYllQwJLMCmLMk=.c02fdb20-d081-4ef1-b295-6cb91998c437@github.com>
References: <0ntxByd7k8donsRMPAXQQciJJjRvPbYllQwJLMCmLMk=.c02fdb20-d081-4ef1-b295-6cb91998c437@github.com>
Message-ID: <uxRd1uZ0xj5tB0pEiaU6iz7W7-cT0A7iBMi9R4vmjoE=.c5c7f849-cf02-4322-97df-6720892cd520@github.com>

> Add accessors for the address of a native function. This follows the jextract principle of exposing all the information that it has.
> 
> The address is useful in cases where a user needs to pass the address of a native function to be used as a callback by another (higher-order) native function.
> 
> Note: while working on this I noticed that the `TestUtils` file was not being rebuilt when dependent tests were running. Many tests depend on this file to compile generated source code for instance. I've added the needed `@build` tags, and `lib.build` property (the latter only works for the tests under `TestNG.dirs`).

Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:

  Fix test typedef

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/228/files
  - new: https://git.openjdk.org/jextract/pull/228/files/c50d8574..2fd79c50

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=228&range=01
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=228&range=00-01

  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jextract/pull/228.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/228/head:pull/228

PR: https://git.openjdk.org/jextract/pull/228

From jvernee at openjdk.org  Fri Apr  5 10:47:35 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Fri, 5 Apr 2024 10:47:35 GMT
Subject: RFR: 7903704: Expose addresses of native functions [v3]
In-Reply-To: <0ntxByd7k8donsRMPAXQQciJJjRvPbYllQwJLMCmLMk=.c02fdb20-d081-4ef1-b295-6cb91998c437@github.com>
References: <0ntxByd7k8donsRMPAXQQciJJjRvPbYllQwJLMCmLMk=.c02fdb20-d081-4ef1-b295-6cb91998c437@github.com>
Message-ID: <Fub1dBW37EK4MynYefj_ptzB83HBSdOuH3JCbszdOvE=.7ecf0cc2-2c2c-4235-b8b6-725da0ad2b16@github.com>

> Add accessors for the address of a native function. This follows the jextract principle of exposing all the information that it has.
> 
> The address is useful in cases where a user needs to pass the address of a native function to be used as a callback by another (higher-order) native function.
> 
> Note: while working on this I noticed that the `TestUtils` file was not being rebuilt when dependent tests were running. Many tests depend on this file to compile generated source code for instance. I've added the needed `@build` tags, and `lib.build` property (the latter only works for the tests under `TestNG.dirs`).

Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:

  add missing build dependencies to tests

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/228/files
  - new: https://git.openjdk.org/jextract/pull/228/files/2fd79c50..01f908d2

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=228&range=02
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=228&range=01-02

  Stats: 2 lines in 2 files changed: 0 ins; 0 del; 2 mod
  Patch: https://git.openjdk.org/jextract/pull/228.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/228/head:pull/228

PR: https://git.openjdk.org/jextract/pull/228

From jvernee at openjdk.org  Fri Apr  5 12:21:09 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Fri, 5 Apr 2024 12:21:09 GMT
Subject: Integrated: 7903704: Expose addresses of native functions
In-Reply-To: <0ntxByd7k8donsRMPAXQQciJJjRvPbYllQwJLMCmLMk=.c02fdb20-d081-4ef1-b295-6cb91998c437@github.com>
References: <0ntxByd7k8donsRMPAXQQciJJjRvPbYllQwJLMCmLMk=.c02fdb20-d081-4ef1-b295-6cb91998c437@github.com>
Message-ID: <8f2liKb988ZMqIKkTnlqRSwUwo-SvgaggvefYbf8S5s=.4fe1b94c-eeab-4a50-b7b6-a9d5c723e242@github.com>

On Tue, 2 Apr 2024 15:08:48 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Add accessors for the address of a native function. This follows the jextract principle of exposing all the information that it has.
> 
> The address is useful in cases where a user needs to pass the address of a native function to be used as a callback by another (higher-order) native function.
> 
> Note: while working on this I noticed that the `TestUtils` file was not being rebuilt when dependent tests were running. Many tests depend on this file to compile generated source code for instance. I've added the needed `@build` tags, and `lib.build` property (the latter only works for the tests under `TestNG.dirs`).

This pull request has now been integrated.

Changeset: 73130fcd
Author:    Jorn Vernee <jvernee at openjdk.org>
URL:       https://git.openjdk.org/jextract/commit/73130fcd7178262055f4e23278ed179c9d67cc75
Stats:     176 lines in 47 files changed: 169 ins; 1 del; 6 mod

7903704: Expose addresses of native functions

Reviewed-by: mcimadamore

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

PR: https://git.openjdk.org/jextract/pull/228

From nlisker at openjdk.org  Sun Apr  7 16:44:29 2024
From: nlisker at openjdk.org (Nir Lisker)
Date: Sun, 7 Apr 2024 16:44:29 GMT
Subject: RFR: Fix simple warnings
Message-ID: <wJ8s4wosG6tofILJnZ_vaNlbb-NsTZI_XuWdRsbG5ZY=.67c72fe6-f6f5-4a0b-ad03-1fa851e0c6d6@github.com>

Fixes for warnings:

* Missing `@Override` annotations
* Unnecessary code (casts and semicolons)
* Unused imports

There are more complicated warnings that should be looked at separately like resource leaks, potential null access, and unused variables.

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

Commit messages:
 - Fix whitespaces
 - Remove unnecessary code
 - Update copyright year
 - Add missing @Override annotations
 - Remove unused imports

Changes: https://git.openjdk.org/jextract/pull/229/files
  Webrev: https://webrevs.openjdk.org/?repo=jextract&pr=229&range=00
  Stats: 41 lines in 17 files changed: 7 ins; 13 del; 21 mod
  Patch: https://git.openjdk.org/jextract/pull/229.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/229/head:pull/229

PR: https://git.openjdk.org/jextract/pull/229

From nlisker at openjdk.org  Sun Apr  7 16:51:18 2024
From: nlisker at openjdk.org (Nir Lisker)
Date: Sun, 7 Apr 2024 16:51:18 GMT
Subject: RFR: Fix simple warnings [v2]
In-Reply-To: <wJ8s4wosG6tofILJnZ_vaNlbb-NsTZI_XuWdRsbG5ZY=.67c72fe6-f6f5-4a0b-ad03-1fa851e0c6d6@github.com>
References: <wJ8s4wosG6tofILJnZ_vaNlbb-NsTZI_XuWdRsbG5ZY=.67c72fe6-f6f5-4a0b-ad03-1fa851e0c6d6@github.com>
Message-ID: <Xga56Jk-rP6-SE-71yx7LbnhsfJQCJxrcppVpqTiBUw=.d282510d-d9c8-46dd-a8a5-d791b67be522@github.com>

> Fixes for warnings:
> 
> * Missing `@Override` annotations
> * Unnecessary code (casts and semicolons)
> * Unused imports
> 
> There are more complicated warnings that should be looked at separately like resource leaks, potential null access, and unused variables.

Nir Lisker has updated the pull request incrementally with one additional commit since the last revision:

  Add newline

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/229/files
  - new: https://git.openjdk.org/jextract/pull/229/files/941c4381..cc54e8b8

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=229&range=01
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=229&range=00-01

  Stats: 1 line in 1 file changed: 1 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/jextract/pull/229.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/229/head:pull/229

PR: https://git.openjdk.org/jextract/pull/229

From jvernee at openjdk.org  Sun Apr  7 20:48:08 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Sun, 7 Apr 2024 20:48:08 GMT
Subject: RFR: Fix simple warnings [v2]
In-Reply-To: <Xga56Jk-rP6-SE-71yx7LbnhsfJQCJxrcppVpqTiBUw=.d282510d-d9c8-46dd-a8a5-d791b67be522@github.com>
References: <wJ8s4wosG6tofILJnZ_vaNlbb-NsTZI_XuWdRsbG5ZY=.67c72fe6-f6f5-4a0b-ad03-1fa851e0c6d6@github.com>
 <Xga56Jk-rP6-SE-71yx7LbnhsfJQCJxrcppVpqTiBUw=.d282510d-d9c8-46dd-a8a5-d791b67be522@github.com>
Message-ID: <JZtIEU5F3O9rUrpJRFOB1UdjEEhMDdXIWkGX8m9OoUA=.f33fe9c5-eac9-44a1-8fa3-a94995b27449@github.com>

On Sun, 7 Apr 2024 16:51:18 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> Fixes for warnings:
>> 
>> * Missing `@Override` annotations
>> * Unnecessary code (casts and semicolons)
>> * Unused imports
>> 
>> There are more complicated warnings that should be looked at separately like resource leaks, potential null access, and unused variables.
>
> Nir Lisker has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Add newline

Looks good. Thanks for the cleanups.

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

Marked as reviewed by jvernee (Committer).

PR Review: https://git.openjdk.org/jextract/pull/229#pullrequestreview-1985249820

From nlisker at openjdk.org  Sun Apr  7 20:53:09 2024
From: nlisker at openjdk.org (Nir Lisker)
Date: Sun, 7 Apr 2024 20:53:09 GMT
Subject: Integrated: Fix simple warnings
In-Reply-To: <wJ8s4wosG6tofILJnZ_vaNlbb-NsTZI_XuWdRsbG5ZY=.67c72fe6-f6f5-4a0b-ad03-1fa851e0c6d6@github.com>
References: <wJ8s4wosG6tofILJnZ_vaNlbb-NsTZI_XuWdRsbG5ZY=.67c72fe6-f6f5-4a0b-ad03-1fa851e0c6d6@github.com>
Message-ID: <rWS6uCPKIRf77oQ4AXond1MIWpoAg4AecgjXhQAJrbU=.a4ec22ec-4186-449f-85da-e39c41da8357@github.com>

On Sun, 7 Apr 2024 16:39:29 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

> Fixes for warnings:
> 
> * Missing `@Override` annotations
> * Unnecessary code (casts and semicolons)
> * Unused imports
> 
> There are more complicated warnings that should be looked at separately like resource leaks, potential null access, and unused variables.

This pull request has now been integrated.

Changeset: 1012e57a
Author:    Nir Lisker <nlisker at openjdk.org>
Committer: Jorn Vernee <jvernee at openjdk.org>
URL:       https://git.openjdk.org/jextract/commit/1012e57acce1aad4c163cd19ffaf7594bdaaef70
Stats:     42 lines in 17 files changed: 8 ins; 13 del; 21 mod

Fix simple warnings

Reviewed-by: jvernee

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

PR: https://git.openjdk.org/jextract/pull/229

From jvernee at openjdk.org  Sun Apr  7 20:59:10 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Sun, 7 Apr 2024 20:59:10 GMT
Subject: RFR: Fix simple warnings [v2]
In-Reply-To: <Xga56Jk-rP6-SE-71yx7LbnhsfJQCJxrcppVpqTiBUw=.d282510d-d9c8-46dd-a8a5-d791b67be522@github.com>
References: <wJ8s4wosG6tofILJnZ_vaNlbb-NsTZI_XuWdRsbG5ZY=.67c72fe6-f6f5-4a0b-ad03-1fa851e0c6d6@github.com>
 <Xga56Jk-rP6-SE-71yx7LbnhsfJQCJxrcppVpqTiBUw=.d282510d-d9c8-46dd-a8a5-d791b67be522@github.com>
Message-ID: <h0l80CoQXZCdv0jE1d5PsrsjOJ-KEP-dNBqhowdWDqE=.1da2a5d7-1308-4deb-8c5c-e15b3f66d874@github.com>

On Sun, 7 Apr 2024 16:51:18 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> Fixes for warnings:
>> 
>> * Missing `@Override` annotations
>> * Unnecessary code (casts and semicolons)
>> * Unused imports
>> 
>> There are more complicated warnings that should be looked at separately like resource leaks, potential null access, and unused variables.
>
> Nir Lisker has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Add newline

Err, looks like one of the changes here results in a compilation failure (and I accidentally tested the wrong branch before approving :/)


> Task :compileJava FAILED
.\src\main\java\org\openjdk\jextract\impl\Utils.java:240: error: not a statement
                    yield double.class;
                    ^
.\src\main\java\org\openjdk\jextract\impl\Utils.java:240: error: ';' expected
                    yield double.class;
                         ^
.\src\main\java\org\openjdk\jextract\impl\Utils.java:240: error: not a statement
                    yield double.class;
                                ^
Note: Some input files use preview features of Java SE 22.
Note: Recompile with -Xlint:preview for details.
3 errors

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

PR Comment: https://git.openjdk.org/jextract/pull/229#issuecomment-2041606913

From jvernee at openjdk.org  Sun Apr  7 21:03:16 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Sun, 7 Apr 2024 21:03:16 GMT
Subject: RFR: Fix compilation failure after #229
Message-ID: <J3PvSGhWw-NdDyOvxxeXNgsKMV8U7TiPBp9f1bA1_eE=.a4c6db9d-059b-4aec-aa83-a2725af094fd@github.com>

Changes in https://github.com/openjdk/jextract/pull/229 result in a compilation failure.

A cast that looks redundant was removed, but is actually needed for the code to compile.

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

Commit messages:
 - Fix compilation failure

Changes: https://git.openjdk.org/jextract/pull/230/files
  Webrev: https://webrevs.openjdk.org/?repo=jextract&pr=230&range=00
  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jextract/pull/230.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/230/head:pull/230

PR: https://git.openjdk.org/jextract/pull/230

From nlisker at openjdk.org  Sun Apr  7 21:12:09 2024
From: nlisker at openjdk.org (Nir Lisker)
Date: Sun, 7 Apr 2024 21:12:09 GMT
Subject: RFR: Fix compilation failure after #229
In-Reply-To: <J3PvSGhWw-NdDyOvxxeXNgsKMV8U7TiPBp9f1bA1_eE=.a4c6db9d-059b-4aec-aa83-a2725af094fd@github.com>
References: <J3PvSGhWw-NdDyOvxxeXNgsKMV8U7TiPBp9f1bA1_eE=.a4c6db9d-059b-4aec-aa83-a2725af094fd@github.com>
Message-ID: <pdO3SCq23fVTtITgKOY4ElC1TzcVyMy_X8SqtwhugJI=.18eb64ae-bd1d-4738-a6c1-395e934db07a@github.com>

On Sun, 7 Apr 2024 20:59:16 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Changes in https://github.com/openjdk/jextract/pull/229 result in a compilation failure.
> 
> A cast that looks redundant was removed, but is actually needed for the code to compile.

Marked as reviewed by nlisker (no project role).

I used Eclipse to compile and it's known to not treat generics exactly the same as javac, so it reported this as an unneeded cast while javac thinks it's needed. I think that Eclipse is correct here, but since the code needs to run on javac we need to appease it.

Still, `case Double -> double.class;` is fine, but

case LongDouble -> {
    if (TypeImpl.IS_WINDOWS) {
        yield double.class;
    }

isn't? They yield the same type.

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

PR Review: https://git.openjdk.org/jextract/pull/230#pullrequestreview-1985253005
PR Comment: https://git.openjdk.org/jextract/pull/230#issuecomment-2041610152

From mcimadamore at openjdk.org  Mon Apr  8 08:03:09 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Mon, 8 Apr 2024 08:03:09 GMT
Subject: RFR: Fix compilation failure after #229
In-Reply-To: <J3PvSGhWw-NdDyOvxxeXNgsKMV8U7TiPBp9f1bA1_eE=.a4c6db9d-059b-4aec-aa83-a2725af094fd@github.com>
References: <J3PvSGhWw-NdDyOvxxeXNgsKMV8U7TiPBp9f1bA1_eE=.a4c6db9d-059b-4aec-aa83-a2725af094fd@github.com>
Message-ID: <qu0qh1h6C5P9MFPFcVAmrVUJNt_Qzlo936cVjeNAISA=.0725e1d2-ba33-4dfc-9e18-b65d55b27a1d@github.com>

On Sun, 7 Apr 2024 20:59:16 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Changes in https://github.com/openjdk/jextract/pull/229 result in a compilation failure.
> 
> A cast that looks redundant was removed, but is actually needed for the code to compile.

Marked as reviewed by mcimadamore (Reviewer).

This problem has been fixed in 23:
https://bugs.openjdk.org/browse/JDK-8321582

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

PR Review: https://git.openjdk.org/jextract/pull/230#pullrequestreview-1985707437
PR Comment: https://git.openjdk.org/jextract/pull/230#issuecomment-2042105635

From jvernee at openjdk.org  Mon Apr  8 12:11:12 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 8 Apr 2024 12:11:12 GMT
Subject: Integrated: Fix compilation failure after #229
In-Reply-To: <J3PvSGhWw-NdDyOvxxeXNgsKMV8U7TiPBp9f1bA1_eE=.a4c6db9d-059b-4aec-aa83-a2725af094fd@github.com>
References: <J3PvSGhWw-NdDyOvxxeXNgsKMV8U7TiPBp9f1bA1_eE=.a4c6db9d-059b-4aec-aa83-a2725af094fd@github.com>
Message-ID: <Js51mNfbZu_5zhmVYWGVZxEqH8fpuoUZ22mRSItfC_g=.a4d5c102-51aa-4151-97f0-937baf392f69@github.com>

On Sun, 7 Apr 2024 20:59:16 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Changes in https://github.com/openjdk/jextract/pull/229 result in a compilation failure.
> 
> A cast that looks redundant was removed, but is actually needed for the code to compile.

This pull request has now been integrated.

Changeset: d700185f
Author:    Jorn Vernee <jvernee at openjdk.org>
URL:       https://git.openjdk.org/jextract/commit/d700185f7b7a11a32b08ec08cc83dae144c41508
Stats:     1 line in 1 file changed: 0 ins; 0 del; 1 mod

Fix compilation failure after #229

Reviewed-by: nlisker, mcimadamore

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

PR: https://git.openjdk.org/jextract/pull/230

From jvernee at openjdk.org  Tue Apr  9 17:24:19 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 9 Apr 2024 17:24:19 GMT
Subject: RFR: Add jextract guide
Message-ID: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>

Add a comprehensive jextract guide under a new `doc/` folder.

This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.

Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

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

Commit messages:
 - Phrasing
 - Section of pre-precessor defines + other languages
 - Polish
 - Update README.md
 - Create GUIDE.md

Changes: https://git.openjdk.org/jextract/pull/231/files
  Webrev: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=00
  Stats: 995 lines in 2 files changed: 824 ins; 171 del; 0 mod
  Patch: https://git.openjdk.org/jextract/pull/231.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/231/head:pull/231

PR: https://git.openjdk.org/jextract/pull/231

From nlisker at openjdk.org  Tue Apr  9 17:34:12 2024
From: nlisker at openjdk.org (Nir Lisker)
Date: Tue, 9 Apr 2024 17:34:12 GMT
Subject: RFR: Add jextract guide
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <Lr1vJvEgTEu559aJf-Tr-0RgKWQMPUR6jmocZxaurZc=.159fe14c-19e7-4d55-bfce-bf640ee379cb@github.com>

On Tue, 9 Apr 2024 17:20:22 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

doc/GUIDE.md line 3:

> 1: # Jextract Guide
> 2: 
> 3: The jextract tool parses header (.h) files of native libraries, and generates Java code,

Aren't .c files also viable for jextract?

doc/GUIDE.md line 4:

> 2: 
> 3: The jextract tool parses header (.h) files of native libraries, and generates Java code,
> 4: called 'bindings', which  use the Foreign Function and Memory API (FFM API) under the hood,

Double space after `which`.

doc/GUIDE.md line 8:

> 6: 
> 7: Interacting with native C code through the FFM API works
> 8: by loading a native library (e.g. a `.so`/`.dll`/`.dylib` file), which is essentially an

Comma after `e.g.`.

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1558058247
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1558058784
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1558060749

From jvernee at openjdk.org  Tue Apr  9 17:40:10 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 9 Apr 2024 17:40:10 GMT
Subject: RFR: Add jextract guide
In-Reply-To: <Lr1vJvEgTEu559aJf-Tr-0RgKWQMPUR6jmocZxaurZc=.159fe14c-19e7-4d55-bfce-bf640ee379cb@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <Lr1vJvEgTEu559aJf-Tr-0RgKWQMPUR6jmocZxaurZc=.159fe14c-19e7-4d55-bfce-bf640ee379cb@github.com>
Message-ID: <j-c35U9m6iRp7Fqzg1Xgzq3in605lrqIMMKJ5QpeXjg=.8ffaabb3-0556-4c89-835b-55553ad059eb@github.com>

On Tue, 9 Apr 2024 17:29:33 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> doc/GUIDE.md line 3:
> 
>> 1: # Jextract Guide
>> 2: 
>> 3: The jextract tool parses header (.h) files of native libraries, and generates Java code,
> 
> Aren't .c files also viable for jextract?

Technically I don't think the extension matters, but C header files typically have the `.h` extension.

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

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

From mcimadamore at openjdk.org  Tue Apr  9 18:08:31 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Tue, 9 Apr 2024 18:08:31 GMT
Subject: RFR: 7903697: Support symbols in header files are alias for different
 name in share library
Message-ID: <zqbW1R_1-RzMOFExvjr5NAtepnxuhKOSv_I1KQja44I=.a53488c5-b4d3-4fe9-aa89-ae2de407f5ad@github.com>

This PR restores a functionality that was available in a (much) older version of jextract.

Basically, some library symbols can have a C name that differs from the symbol found in the shared library. This is typically done using an attribute (AsmLabelAttr). We already have code to parse declaration attributes, but when we switched to the new FFM-based jextract, we didn't update code generation to use the aliased name for the symbol lookup, if one was available.

I've resurrected the old test to check this functionality, with some changes: the original test also tested Windows support, but that seems less important, given that Windows doesn't really have an equivalent feature/attribute.

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

Commit messages:
 - Initial push

Changes: https://git.openjdk.org/jextract/pull/232/files
  Webrev: https://webrevs.openjdk.org/?repo=jextract&pr=232&range=00
  Issue: https://bugs.openjdk.org/browse/CODETOOLS-7903697
  Stats: 208 lines in 5 files changed: 203 ins; 0 del; 5 mod
  Patch: https://git.openjdk.org/jextract/pull/232.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/232/head:pull/232

PR: https://git.openjdk.org/jextract/pull/232

From jvernee at openjdk.org  Tue Apr  9 19:15:09 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 9 Apr 2024 19:15:09 GMT
Subject: RFR: 7903697: Support symbols in header files are alias for
 different name in share library
In-Reply-To: <zqbW1R_1-RzMOFExvjr5NAtepnxuhKOSv_I1KQja44I=.a53488c5-b4d3-4fe9-aa89-ae2de407f5ad@github.com>
References: <zqbW1R_1-RzMOFExvjr5NAtepnxuhKOSv_I1KQja44I=.a53488c5-b4d3-4fe9-aa89-ae2de407f5ad@github.com>
Message-ID: <pXM29K1IAuzhw_8ccMQocfq_CkEsqX1K22DYEI4IRPc=.15f6d74e-4b86-47c5-be11-a2221ea4798b@github.com>

On Tue, 9 Apr 2024 17:53:02 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This PR restores a functionality that was available in a (much) older version of jextract.
> 
> Basically, some library symbols can have a C name that differs from the symbol found in the shared library. This is typically done using an attribute (AsmLabelAttr). We already have code to parse declaration attributes, but when we switched to the new FFM-based jextract, we didn't update code generation to use the aliased name for the symbol lookup, if one was available.
> 
> I've resurrected the old test to check this functionality, with some changes: the original test also tested Windows support, but that seems less important, given that Windows doesn't really have an equivalent feature/attribute.

Marked as reviewed by jvernee (Committer).

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

PR Review: https://git.openjdk.org/jextract/pull/232#pullrequestreview-1989978474

From jvernee at openjdk.org  Tue Apr  9 20:18:10 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 9 Apr 2024 20:18:10 GMT
Subject: RFR: Add jextract guide
In-Reply-To: <Lr1vJvEgTEu559aJf-Tr-0RgKWQMPUR6jmocZxaurZc=.159fe14c-19e7-4d55-bfce-bf640ee379cb@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <Lr1vJvEgTEu559aJf-Tr-0RgKWQMPUR6jmocZxaurZc=.159fe14c-19e7-4d55-bfce-bf640ee379cb@github.com>
Message-ID: <YaUFXfKSmF5-yhUClvfE1FKHiqfezPnXWuGcB8hKYUw=.1312dd57-3a1e-46fa-bb16-b08055030a33@github.com>

On Tue, 9 Apr 2024 17:31:47 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> doc/GUIDE.md line 8:
> 
>> 6: 
>> 7: Interacting with native C code through the FFM API works
>> 8: by loading a native library (e.g. a `.so`/`.dll`/`.dylib` file), which is essentially an
> 
> Comma after `e.g.`.

You mean add a comma like `e.g., ...`?

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

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

From bpb at openjdk.org  Tue Apr  9 21:47:09 2024
From: bpb at openjdk.org (Brian Burkhalter)
Date: Tue, 9 Apr 2024 21:47:09 GMT
Subject: RFR: 7903697: Support symbols in header files are alias for
 different name in share library
In-Reply-To: <zqbW1R_1-RzMOFExvjr5NAtepnxuhKOSv_I1KQja44I=.a53488c5-b4d3-4fe9-aa89-ae2de407f5ad@github.com>
References: <zqbW1R_1-RzMOFExvjr5NAtepnxuhKOSv_I1KQja44I=.a53488c5-b4d3-4fe9-aa89-ae2de407f5ad@github.com>
Message-ID: <iz8bygpogha1suyFJkw7zyktYTWWeZyNKne6SUi1t6E=.fa3bcfb3-7ea8-44ae-b001-6d997b6656cf@github.com>

On Tue, 9 Apr 2024 17:53:02 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This PR restores a functionality that was available in a (much) older version of jextract.
> 
> Basically, some library symbols can have a C name that differs from the symbol found in the shared library. This is typically done using an attribute (AsmLabelAttr). We already have code to parse declaration attributes, but when we switched to the new FFM-based jextract, we didn't update code generation to use the aliased name for the symbol lookup, if one was available.
> 
> I've resurrected the old test to check this functionality, with some changes: the original test also tested Windows support, but that seems less important, given that Windows doesn't really have an equivalent feature/attribute.

I am not qualified to approve this PR, but I am glad to see that the problem is being addressed promptly.

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

PR Comment: https://git.openjdk.org/jextract/pull/232#issuecomment-2046099726

From mcimadamore at openjdk.org  Wed Apr 10 09:27:25 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 10 Apr 2024 09:27:25 GMT
Subject: RFR: 7903697: jextract doesn't use name in asm label attribute
 [v2]
In-Reply-To: <zqbW1R_1-RzMOFExvjr5NAtepnxuhKOSv_I1KQja44I=.a53488c5-b4d3-4fe9-aa89-ae2de407f5ad@github.com>
References: <zqbW1R_1-RzMOFExvjr5NAtepnxuhKOSv_I1KQja44I=.a53488c5-b4d3-4fe9-aa89-ae2de407f5ad@github.com>
Message-ID: <jrykbGnPFY_2liscopsKsXUVqBpv13RIQXg6HwGj9LQ=.1b9609c1-b0ce-41f5-9753-e3f619caf0b3@github.com>

> This PR restores a functionality that was available in a (much) older version of jextract.
> 
> Basically, some library symbols can have a C name that differs from the symbol found in the shared library. This is typically done using an attribute (AsmLabelAttr). We already have code to parse declaration attributes, but when we switched to the new FFM-based jextract, we didn't update code generation to use the aliased name for the symbol lookup, if one was available.
> 
> I've resurrected the old test to check this functionality, with some changes: the original test also tested Windows support, but that seems less important, given that Windows doesn't really have an equivalent feature/attribute.

Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:

  Tweak header file in test

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/232/files
  - new: https://git.openjdk.org/jextract/pull/232/files/7d07c827..e94bbb85

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=232&range=01
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=232&range=00-01

  Stats: 6 lines in 1 file changed: 0 ins; 4 del; 2 mod
  Patch: https://git.openjdk.org/jextract/pull/232.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/232/head:pull/232

PR: https://git.openjdk.org/jextract/pull/232

From mcimadamore at openjdk.org  Wed Apr 10 09:32:12 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 10 Apr 2024 09:32:12 GMT
Subject: RFR: Add jextract guide
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <VFuu4wwuWcSDQ-7mNjkHoFnA5GXXh5wfXHRPnLOE2EY=.83576cff-70c3-4db2-afb4-3c35670622ba@github.com>

On Tue, 9 Apr 2024 17:20:22 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

doc/GUIDE.md line 4:

> 2: 
> 3: The jextract tool parses header (.h) files of native libraries, and generates Java code,
> 4: called 'bindings', which  use the Foreign Function and Memory API (FFM API) under the hood,

maybe add a link for FFM to the final JEP, so that readers who want to know more can do so?

doc/GUIDE.md line 4:

> 2: 
> 3: The jextract tool parses header (.h) files of native libraries, and generates Java code,
> 4: called 'bindings', which  use the Foreign Function and Memory API (FFM API) under the hood,

There's several words in the documents which are wrapped in single quotes. Should we use italic here, or bold?

doc/GUIDE.md line 15:

> 13: returned by a lookup, and construct `MemoryLayout` instances for the structs they want to access.
> 14: Jextract aims to automate many of these steps, so that a client can instead immediately start
> 15: using a native library they are interested in.

I suggest using `the native library` (because it's the one they are interested in). Also consider using plural (e.g. the native libraries).

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559133910
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559135755
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559138201

From mcimadamore at openjdk.org  Wed Apr 10 09:38:10 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 10 Apr 2024 09:38:10 GMT
Subject: RFR: Add jextract guide
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <YvbvYKrCROOncFAE8ApKwsOcok5E_lst68sM8fEfOp0=.51fc5f18-c0f7-49e8-84aa-df80035c7cf9@github.com>

On Tue, 9 Apr 2024 17:20:22 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

doc/GUIDE.md line 25:

> 23: ## Running Jextract
> 24: 
> 25: A native library typically has an `include` directory which contains all the header files

Here I wonder if instead of using pseudo name for paths, we should use some more real-looking names, like `/usr/include` and `/usr/lib`, which are common in many NIX systems.

doc/GUIDE.md line 28:

> 26: that define the interface of the library, with one 'main' header file. Let's say we have a
> 27: library called `mylib` stored at `/path/to/mylib` that has a directory `/path/to/mylib/include`
> 28: with all the header files. And let's say that we have a shell open in the root directory

Maybe instead of `with all the header files` we could expand to `where the header files of that library are stored`

doc/GUIDE.md line 29:

> 27: library called `mylib` stored at `/path/to/mylib` that has a directory `/path/to/mylib/include`
> 28: with all the header files. And let's say that we have a shell open in the root directory
> 29: of the Java project we're working on, which has an `src` source directory corresponding to

Suggestion:

of the Java project we're working on, which has a `src` source directory corresponding to

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559142532
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559144738
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559141069

From mcimadamore at openjdk.org  Wed Apr 10 09:44:14 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 10 Apr 2024 09:44:14 GMT
Subject: RFR: Add jextract guide
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <jDPjz2EWhBMWcT1oaSdBh82AwQXb0xh_zF9NTtIa1PA=.e5c8a670-46cd-4164-82ac-710bbf271d57@github.com>

On Tue, 9 Apr 2024 17:20:22 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

doc/GUIDE.md line 63:

> 61: Therefore, jextract is intended to be run once, and then for the generated sources to be added to the project.
> 62: Jextract only needs to be run again when the native library, or jextract itself are updated. (This is also
> 63: the workflow that jextract itself uses for talking to the libclang library).

Suggestion:

the workflow that jextract itself follows: jextract depends on the libclang (link?) native library in order to parse C sources).

doc/GUIDE.md line 68:

> 66: 
> 67: When using the `--library <libspec>` option, the generated code internally uses [`SymbolLookup::libraryLookup`](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/foreign/SymbolLookup.html#libraryLookup(java.nio.file.Path,java.lang.foreign.Arena))
> 68: to load libraries specified by `<libspec>`, after potentially mapping the name of the library to a platform dependent name using [`System::mapLibraryName`](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/System.html#mapLibraryName(java.lang.String)).

potentially? Are there cases where mapping a library name is a no-op?

doc/GUIDE.md line 72:

> 70: library loading mechanism on Linux, which is [`dlopen`](https://man7.org/linux/man-pages/man3/dlopen.3.html).
> 71: This way of loading libraries also relies on OS-specific search mechanisms to find the library file.
> 72: On Linux the search path can be ammended using the `LD_LIBRARY_PATH` environment variable (see the documentation of `dlopen`).

Suggestion:

On Linux the search path can be amended using the `LD_LIBRARY_PATH` environment variable (see the documentation of `dlopen`).

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559150878
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559151912
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559153321

From mcimadamore at openjdk.org  Wed Apr 10 09:56:13 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 10 Apr 2024 09:56:13 GMT
Subject: RFR: Add jextract guide
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <ZaTeKSCMpTglGB4uCtulQQJtfqBc3GbFOlNwT9riP_M=.ef94c5af-1336-4d24-9937-4f970db8e310@github.com>

On Tue, 9 Apr 2024 17:20:22 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

doc/GUIDE.md line 135:

> 133: ### Builtin Type Layouts
> 134: 
> 135: For every jextract run, regardless of the contents of the library header files, jextract

I'm not sure it's clear where these layouts definitions are introduced. I think the text should say that these are appended to the main header class.

doc/GUIDE.md line 253:

> 251: Note that the enum constants are exposed as top-level methods, rather than being nested
> 252: inside a class called `MY_ENUM`, or through the use of a Java `enum`. This translation
> 253: strategy mimics C's behavior of enum constants being accessible as a top-level declaration

There's another reason as well for not using enums - which is that, in C, you can use bitwise operations to denote enum sets - e.g. `RED | GREEN` (and other more crazy stuff), which would not be possible using Java enums. At its core, a C enum is just a glorified int.

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

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

From mcimadamore at openjdk.org  Wed Apr 10 09:56:13 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 10 Apr 2024 09:56:13 GMT
Subject: RFR: Add jextract guide
In-Reply-To: <ZaTeKSCMpTglGB4uCtulQQJtfqBc3GbFOlNwT9riP_M=.ef94c5af-1336-4d24-9937-4f970db8e310@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <ZaTeKSCMpTglGB4uCtulQQJtfqBc3GbFOlNwT9riP_M=.ef94c5af-1336-4d24-9937-4f970db8e310@github.com>
Message-ID: <D84_sXAAFLHmZ7DK2I-rAdu7Eyb36GQ5l95eFld3HDQ=.ed101aaf-b737-49d0-8e3c-1e508b6c3b0a@github.com>

On Wed, 10 Apr 2024 09:50:06 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> doc/GUIDE.md line 135:
> 
>> 133: ### Builtin Type Layouts
>> 134: 
>> 135: For every jextract run, regardless of the contents of the library header files, jextract
> 
> I'm not sure it's clear where these layouts definitions are introduced. I think the text should say that these are appended to the main header class.

Perhaps you can add a comment:

// mylib_h.java

as you do in later examples?

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

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

From mcimadamore at openjdk.org  Wed Apr 10 10:01:14 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 10 Apr 2024 10:01:14 GMT
Subject: RFR: Add jextract guide
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <AeZHQmGpIoIHwRGfWj__qDBc1EeLHHI2U561zCQWDj8=.3f7769e6-17d7-4afa-aecc-f459923a15d9@github.com>

On Tue, 9 Apr 2024 17:20:22 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

doc/GUIDE.md line 257:

> 255: 
> 256: Not all types of macros are supported though. Only macros that have a primitive numerical
> 257: value, a string, or a pointer type are supported. Most notably, function-like macros are

Several people wonder what to do when dealing with a library that is heavy in its use of function-like macros. There's two strategies here - the first is to replicate the code in the function-like macro in Java, using FFM. The second is to create a small C library which turns the function-like macro into a proper function, so that it can be used from FFM. Not sure we want to add this detail here (or maybe in an appendix).

doc/GUIDE.md line 309:

> 307: ```
> 308: 
> 309: There's a getter and setter for each field of the struct (1), which takes a pointer to a struct

I see you didn't use bullet lists much, but I wonder if one would be helpful here instead of a single long para? Perhaps even a numbered list, where the number refers to the comment in the code?

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

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

From mcimadamore at openjdk.org  Wed Apr 10 10:14:16 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 10 Apr 2024 10:14:16 GMT
Subject: RFR: Add jextract guide
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <w6AAzGser9cwc6Gp61h1fhLdaTwlS_my8Q_sTAvyCgo=.4ab24817-c24c-4687-9097-ea2978b80305@github.com>

On Tue, 9 Apr 2024 17:20:22 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

doc/GUIDE.md line 392:

> 390: ### Function Pointers
> 391: 
> 392: If jextract finds a function pointer type in the header files it parses, it will generate

More directly: `Jextract will generate a separate class for each function pointer type found in the header files it parses.`

doc/GUIDE.md line 420:

> 418: We again have a meta-data accessor for the function descriptor (`descriptor()`). There's
> 419: an `allocate` method that can be used to allocate a new instance of this function pointer,
> 420: who's implementation is implemented by the `fi` functional interface instance. And finally,

Suggestion:

whose implementation is defined by the `fi` functional interface instance. And finally,

doc/GUIDE.md line 448:

> 446: 
> 447: Here we use the lambda `(a, b) -> a * b` as the implementation of the `callback_t` instance
> 448: we create using the call to `allocate`. This method returns an upcall stub like the ones

Suggestion:

we create using `allocate`. This method returns an upcall stub like the ones

doc/GUIDE.md line 449:

> 447: Here we use the lambda `(a, b) -> a * b` as the implementation of the `callback_t` instance
> 448: we create using the call to `allocate`. This method returns an upcall stub like the ones
> 449: returned by the `java.lang.foreign.Linker::upcallStub` method. The `arena` argument denotes

Should there be a link here - like we did for symbol lookup?

doc/GUIDE.md line 451:

> 449: returned by the `java.lang.foreign.Linker::upcallStub` method. The `arena` argument denotes
> 450: the lifetime of the upcall stub, meaning that the upcall stub will be freed when the arena
> 451: is closed (after which the callback instance should no longer be called).

"should not be called" seems to imply that if we call it something bad happens, but we can call it (e.g. it's up to our "goodwill"). "can no longer be called" seems more appropriate?

doc/GUIDE.md line 486:

> 484: `callback_t` instance.
> 485: 
> 486: Jextract generates function pointer classes like the `callback_t` class for function

I know what you mean here - but I wonder if readers will get it w/o some kind of example.

doc/GUIDE.md line 493:

> 491: 
> 492: Jextract handles variadic functions differently from regular functions. Variadic functions
> 493: in C more or less like a template, where the calling convention changes based on the number

Suggestion:

in C behave more or less like a template, where the calling convention changes based on the number

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559178430
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559179645
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559181255
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559181887
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559183287
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559187645
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559188565

From mcimadamore at openjdk.org  Wed Apr 10 10:14:16 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 10 Apr 2024 10:14:16 GMT
Subject: RFR: Add jextract guide
In-Reply-To: <w6AAzGser9cwc6Gp61h1fhLdaTwlS_my8Q_sTAvyCgo=.4ab24817-c24c-4687-9097-ea2978b80305@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <w6AAzGser9cwc6Gp61h1fhLdaTwlS_my8Q_sTAvyCgo=.4ab24817-c24c-4687-9097-ea2978b80305@github.com>
Message-ID: <J7f6QLeK6Rs4KI6ao5Z4VyWsh6BZ9M4-DuAsn6HeuyM=.8c31ab44-669f-49c5-88f6-435444b0887c@github.com>

On Wed, 10 Apr 2024 10:06:37 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> doc/GUIDE.md line 451:
> 
>> 449: returned by the `java.lang.foreign.Linker::upcallStub` method. The `arena` argument denotes
>> 450: the lifetime of the upcall stub, meaning that the upcall stub will be freed when the arena
>> 451: is closed (after which the callback instance should no longer be called).
> 
> "should not be called" seems to imply that if we call it something bad happens, but we can call it (e.g. it's up to our "goodwill"). "can no longer be called" seems more appropriate?

Of course, if the native code stashes the function pointer in a variable somewhere, it would be possible for it to call the func pointer again. But what I meant is that, in principle, FFM should give you an exception when trying to call `call_me_back` again after the arena has been closed, or calling `callback_t::invoke` on a closed segment.

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

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

From mcimadamore at openjdk.org  Wed Apr 10 10:23:11 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 10 Apr 2024 10:23:11 GMT
Subject: RFR: Add jextract guide
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <6I60qUx9nsLYSvwNGWl_sNVE3oCHGvqrL0fVcgQFpoY=.16b61eb6-cbf0-473c-9a8f-7122927cd164@github.com>

On Tue, 9 Apr 2024 17:20:22 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

doc/GUIDE.md line 14:

> 12: Java functions using `Linker::upcallStub`, access global variables through the addresses
> 13: returned by a lookup, and construct `MemoryLayout` instances for the structs they want to access.
> 14: Jextract aims to automate many of these steps, so that a client can instead immediately start

If you want to avoid capitalization of `jextract` you can say `The jextract tool...`

doc/GUIDE.md line 660:

> 658: ## Filtering
> 659: 
> 660: Some libraries are incredibly large (such as a platform SDK), and we might not be

Should we just say `windows.h` instead of the more vague "platform SDK" ?

doc/GUIDE.md line 665:

> 663: the elements we specify.
> 664: 
> 665: To allow for symbol filtering, `jextract` can generate a _dump_ of all the symbols

I noticed that in these sections, refrerences to `jextract` use a code block, whereas in the rest of the document they don't. I don't have a strong preference for one or the other, but we should make that consistent.

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559200246
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559196211
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559198874

From mcimadamore at openjdk.org  Wed Apr 10 10:29:17 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 10 Apr 2024 10:29:17 GMT
Subject: RFR: Add jextract guide
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <FQ0gE9Z270cQUJEZSAwEV8RoOOa8-U6Qji25lgTKiy4=.61ab603a-b588-4ffe-b897-e74b385cd0f5@github.com>

On Tue, 9 Apr 2024 17:20:22 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

doc/GUIDE.md line 781:

> 779: 
> 780: Please note that other header files included by jextract may also define macro values using
> 781: the `#define` pre-processor directive. Therefore it is often important in which order

There seems to be issues with this sentence. Possible suggestion:

`It is therefore important to notice the order in which header files are processed by a compiler, as feeding header files to jextract in the wrong order may result in weird errors due to missing macro definitions`

doc/GUIDE.md line 808:

> 806: ### Additional clang options
> 807: 
> 808: Users can also specify additional clang compiler options, by creating a file named

Maybe here we should start by saying that `jextract` uses clang to parse C files. And if additional options need to be passed to the clang instance used by jextract...

doc/GUIDE.md line 814:

> 812: ## Other Languages
> 813: 
> 814: As noted in the introduction, jextract currently only supports C header files, but many

Should we say something about many libraries (e.g. libclang) providing a C interop wrapper around their C++ impl?

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559204281
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559205783
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559207077

From mcimadamore at openjdk.org  Wed Apr 10 11:27:10 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 10 Apr 2024 11:27:10 GMT
Subject: Integrated: 7903697: jextract doesn't use name in asm label attribute
In-Reply-To: <zqbW1R_1-RzMOFExvjr5NAtepnxuhKOSv_I1KQja44I=.a53488c5-b4d3-4fe9-aa89-ae2de407f5ad@github.com>
References: <zqbW1R_1-RzMOFExvjr5NAtepnxuhKOSv_I1KQja44I=.a53488c5-b4d3-4fe9-aa89-ae2de407f5ad@github.com>
Message-ID: <3OhSU-9ntUizD0C7moAxXOkfsw21EKE_3VgDyx0DHM0=.b093b595-aabb-401e-a962-549a459e8b74@github.com>

On Tue, 9 Apr 2024 17:53:02 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This PR restores a functionality that was available in a (much) older version of jextract.
> 
> Basically, some library symbols can have a C name that differs from the symbol found in the shared library. This is typically done using an attribute (AsmLabelAttr). We already have code to parse declaration attributes, but when we switched to the new FFM-based jextract, we didn't update code generation to use the aliased name for the symbol lookup, if one was available.
> 
> I've resurrected the old test to check this functionality, with some changes: the original test also tested Windows support, but that seems less important, given that Windows doesn't really have an equivalent feature/attribute.

This pull request has now been integrated.

Changeset: 1283561c
Author:    Maurizio Cimadamore <mcimadamore at openjdk.org>
URL:       https://git.openjdk.org/jextract/commit/1283561c5c85b3ff28203891262047d3de451cd5
Stats:     204 lines in 5 files changed: 199 ins; 0 del; 5 mod

7903697: jextract doesn't use name in asm label attribute

Reviewed-by: jvernee

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

PR: https://git.openjdk.org/jextract/pull/232

From jvernee at openjdk.org  Wed Apr 10 13:28:19 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Wed, 10 Apr 2024 13:28:19 GMT
Subject: RFR: Add jextract guide
In-Reply-To: <FQ0gE9Z270cQUJEZSAwEV8RoOOa8-U6Qji25lgTKiy4=.61ab603a-b588-4ffe-b897-e74b385cd0f5@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <FQ0gE9Z270cQUJEZSAwEV8RoOOa8-U6Qji25lgTKiy4=.61ab603a-b588-4ffe-b897-e74b385cd0f5@github.com>
Message-ID: <-6pi6TNB1TypTuS-jpqby-fVBVHuTDe39Be39g1URGs=.5e1a0f1f-561f-46ab-be96-3967c1c2f5c4@github.com>

On Wed, 10 Apr 2024 10:26:28 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> doc/GUIDE.md line 814:
> 
>> 812: ## Other Languages
>> 813: 
>> 814: As noted in the introduction, jextract currently only supports C header files, but many
> 
> Should we say something about many libraries (e.g. libclang) providing a C interop wrapper around their C++ impl?

That's in the table below: `many C++ libraries have a C interface`

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

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

From jvernee at openjdk.org  Wed Apr 10 13:38:16 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Wed, 10 Apr 2024 13:38:16 GMT
Subject: RFR: Add jextract guide
In-Reply-To: <YvbvYKrCROOncFAE8ApKwsOcok5E_lst68sM8fEfOp0=.51fc5f18-c0f7-49e8-84aa-df80035c7cf9@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <YvbvYKrCROOncFAE8ApKwsOcok5E_lst68sM8fEfOp0=.51fc5f18-c0f7-49e8-84aa-df80035c7cf9@github.com>
Message-ID: <zMykeEd7PbeMoo_HeBpq067Zf1KvhHIxa_gGn8JbsGI=.0b453040-832f-4397-b4bd-b34124d0caf3@github.com>

On Wed, 10 Apr 2024 09:32:13 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> doc/GUIDE.md line 29:
> 
>> 27: library called `mylib` stored at `/path/to/mylib` that has a directory `/path/to/mylib/include`
>> 28: with all the header files. And let's say that we have a shell open in the root directory
>> 29: of the Java project we're working on, which has an `src` source directory corresponding to
> 
> Suggestion:
> 
> of the Java project we're working on, which has a `src` source directory corresponding to

It depends on how you read `src`. If you read S R C, then `an` is appropriate.

> doc/GUIDE.md line 68:
> 
>> 66: 
>> 67: When using the `--library <libspec>` option, the generated code internally uses [`SymbolLookup::libraryLookup`](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/foreign/SymbolLookup.html#libraryLookup(java.nio.file.Path,java.lang.foreign.Arena))
>> 68: to load libraries specified by `<libspec>`, after potentially mapping the name of the library to a platform dependent name using [`System::mapLibraryName`](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/System.html#mapLibraryName(java.lang.String)).
> 
> potentially? Are there cases where mapping a library name is a no-op?

The `<libspec>` might be a path (using `:`), in which case we don't  do any mapping, right? I don't mind removing the `potentially` here though.

> doc/GUIDE.md line 257:
> 
>> 255: 
>> 256: Not all types of macros are supported though. Only macros that have a primitive numerical
>> 257: value, a string, or a pointer type are supported. Most notably, function-like macros are
> 
> Several people wonder what to do when dealing with a library that is heavy in its use of function-like macros. There's two strategies here - the first is to replicate the code in the function-like macro in Java, using FFM. The second is to create a small C library which turns the function-like macro into a proper function, so that it can be used from FFM. Not sure we want to add this detail here (or maybe in an appendix).

I think something like that is good to add here. This guide is meant to be comprehensive. If we think some information is useful in the use of jextract, let's add it to the guide.

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559449360
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559446730
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559444213

From mcimadamore at openjdk.org  Wed Apr 10 13:38:17 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 10 Apr 2024 13:38:17 GMT
Subject: RFR: Add jextract guide
In-Reply-To: <-6pi6TNB1TypTuS-jpqby-fVBVHuTDe39Be39g1URGs=.5e1a0f1f-561f-46ab-be96-3967c1c2f5c4@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <FQ0gE9Z270cQUJEZSAwEV8RoOOa8-U6Qji25lgTKiy4=.61ab603a-b588-4ffe-b897-e74b385cd0f5@github.com>
 <-6pi6TNB1TypTuS-jpqby-fVBVHuTDe39Be39g1URGs=.5e1a0f1f-561f-46ab-be96-3967c1c2f5c4@github.com>
Message-ID: <GigzCWrs_-PeCpUbW3bPRP5O_H7J18mg6DcCWQCxx2k=.2ef8a8ba-e585-431b-8324-2ebf718dcff7@github.com>

On Wed, 10 Apr 2024 13:26:10 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> doc/GUIDE.md line 814:
>> 
>>> 812: ## Other Languages
>>> 813: 
>>> 814: As noted in the introduction, jextract currently only supports C header files, but many
>> 
>> Should we say something about many libraries (e.g. libclang) providing a C interop wrapper around their C++ impl?
>
> That's in the table below: `many C++ libraries have a C interface`

whoops - true. I thought that row talked about manually writing a C wrapper around a C++ API.

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

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

From jvernee at openjdk.org  Wed Apr 10 13:49:43 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Wed, 10 Apr 2024 13:49:43 GMT
Subject: RFR: Add jextract guide [v2]
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <XhoLuCzz_LuJb60IG7CfcsArq5KbEUntDQkIx7Dv0CI=.9a0da56c-368f-4445-b165-d36ecd769a2b@github.com>

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link 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 at users.noreply.github.com>

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/231/files
  - new: https://git.openjdk.org/jextract/pull/231/files/01710e76..15776ccc

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=01
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=00-01

  Stats: 4 lines in 1 file changed: 0 ins; 0 del; 4 mod
  Patch: https://git.openjdk.org/jextract/pull/231.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/231/head:pull/231

PR: https://git.openjdk.org/jextract/pull/231

From jvernee at openjdk.org  Wed Apr 10 13:49:43 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Wed, 10 Apr 2024 13:49:43 GMT
Subject: RFR: Add jextract guide [v2]
In-Reply-To: <VFuu4wwuWcSDQ-7mNjkHoFnA5GXXh5wfXHRPnLOE2EY=.83576cff-70c3-4db2-afb4-3c35670622ba@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <VFuu4wwuWcSDQ-7mNjkHoFnA5GXXh5wfXHRPnLOE2EY=.83576cff-70c3-4db2-afb4-3c35670622ba@github.com>
Message-ID: <z75fNrbSLzgyeJZL6yVKeD819cgSol6tdnv3EsjhhJk=.bac109d7-00f9-4d2e-9f4e-747cb174b435@github.com>

On Wed, 10 Apr 2024 09:28:15 GMT, Maurizio Cimadamore <mcimadamore at 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 at users.noreply.github.com>
>
> doc/GUIDE.md line 4:
> 
>> 2: 
>> 3: The jextract tool parses header (.h) files of native libraries, and generates Java code,
>> 4: called 'bindings', which  use the Foreign Function and Memory API (FFM API) under the hood,
> 
> There's several words in the documents which are wrapped in single quotes. Should we use italic here, or bold?

Let's use italic, as that's the style we often use in the javadoc as well

> doc/GUIDE.md line 25:
> 
>> 23: ## Running Jextract
>> 24: 
>> 25: A native library typically has an `include` directory which contains all the header files
> 
> Here I wonder if instead of using pseudo name for paths, we should use some more real-looking names, like `/usr/include` and `/usr/lib`, which are common in many NIX systems.

I kind of wanted to hint at the fact that all library packages should have an `include` directory. The `/usr/include` directory can seem like a special NIX system path where libraries are installed, but that's more a quirk of the package manager which chooses to put the headers of all libraries in the same directory.

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

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

From mcimadamore at openjdk.org  Wed Apr 10 14:03:13 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 10 Apr 2024 14:03:13 GMT
Subject: RFR: Add jextract guide [v2]
In-Reply-To: <zMykeEd7PbeMoo_HeBpq067Zf1KvhHIxa_gGn8JbsGI=.0b453040-832f-4397-b4bd-b34124d0caf3@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <YvbvYKrCROOncFAE8ApKwsOcok5E_lst68sM8fEfOp0=.51fc5f18-c0f7-49e8-84aa-df80035c7cf9@github.com>
 <zMykeEd7PbeMoo_HeBpq067Zf1KvhHIxa_gGn8JbsGI=.0b453040-832f-4397-b4bd-b34124d0caf3@github.com>
Message-ID: <lC7rmhg4ZJpNM9cp81xjqrXR7mfeQJ-jFxtG8ZEFzIA=.7f84c20b-d08c-4bfd-96d9-14f53df725a4@github.com>

On Wed, 10 Apr 2024 13:33:36 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> doc/GUIDE.md line 68:
>> 
>>> 66: 
>>> 67: When using the `--library <libspec>` option, the generated code internally uses [`SymbolLookup::libraryLookup`](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/foreign/SymbolLookup.html#libraryLookup(java.nio.file.Path,java.lang.foreign.Arena))
>>> 68: to load libraries specified by `<libspec>`, after potentially mapping the name of the library to a platform dependent name using [`System::mapLibraryName`](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/System.html#mapLibraryName(java.lang.String)).
>> 
>> potentially? Are there cases where mapping a library name is a no-op?
>
> The `<libspec>` might be a path (using `:`), in which case we don't  do any mapping, right? I don't mind removing the `potentially` here though.

ah I see. I mistakenly read `<libspec>` as if it was a library name.

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

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

From mcimadamore at openjdk.org  Wed Apr 10 14:03:13 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 10 Apr 2024 14:03:13 GMT
Subject: RFR: Add jextract guide [v2]
In-Reply-To: <lC7rmhg4ZJpNM9cp81xjqrXR7mfeQJ-jFxtG8ZEFzIA=.7f84c20b-d08c-4bfd-96d9-14f53df725a4@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <YvbvYKrCROOncFAE8ApKwsOcok5E_lst68sM8fEfOp0=.51fc5f18-c0f7-49e8-84aa-df80035c7cf9@github.com>
 <zMykeEd7PbeMoo_HeBpq067Zf1KvhHIxa_gGn8JbsGI=.0b453040-832f-4397-b4bd-b34124d0caf3@github.com>
 <lC7rmhg4ZJpNM9cp81xjqrXR7mfeQJ-jFxtG8ZEFzIA=.7f84c20b-d08c-4bfd-96d9-14f53df725a4@github.com>
Message-ID: <CJyduahufL2jtbQXJhldSw-WxNUzCiznh7vGzjPUjw4=.57135895-158a-4edd-ba3e-f7e8154a1d30@github.com>

On Wed, 10 Apr 2024 13:56:11 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> The `<libspec>` might be a path (using `:`), in which case we don't  do any mapping, right? I don't mind removing the `potentially` here though.
>
> ah I see. I mistakenly read `<libspec>` as if it was a library name.

In that case, I think it would be clearer if we broke up the sentence. E.g. 


When using the --library <libspec> option, the generated code internally uses SymbolLookup::libraryLookup
to load libraries specified by `<libspec>`. If `<libspec>` denotes a library name, the name is then mapped to a platform dependent name using System::mapLibraryName.

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

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

From jvernee at openjdk.org  Wed Apr 10 14:03:14 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Wed, 10 Apr 2024 14:03:14 GMT
Subject: RFR: Add jextract guide [v2]
In-Reply-To: <J7f6QLeK6Rs4KI6ao5Z4VyWsh6BZ9M4-DuAsn6HeuyM=.8c31ab44-669f-49c5-88f6-435444b0887c@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <w6AAzGser9cwc6Gp61h1fhLdaTwlS_my8Q_sTAvyCgo=.4ab24817-c24c-4687-9097-ea2978b80305@github.com>
 <J7f6QLeK6Rs4KI6ao5Z4VyWsh6BZ9M4-DuAsn6HeuyM=.8c31ab44-669f-49c5-88f6-435444b0887c@github.com>
Message-ID: <uUqSv6eYDD5QEfpdpYxo1Px1qJkz4tVUjDLZCkft3KA=.c573f263-6f55-46a6-8e6e-4983692555cf@github.com>

On Wed, 10 Apr 2024 10:08:25 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> doc/GUIDE.md line 451:
>> 
>>> 449: returned by the `java.lang.foreign.Linker::upcallStub` method. The `arena` argument denotes
>>> 450: the lifetime of the upcall stub, meaning that the upcall stub will be freed when the arena
>>> 451: is closed (after which the callback instance should no longer be called).
>> 
>> "should not be called" seems to imply that if we call it something bad happens, but we can call it (e.g. it's up to our "goodwill"). "can no longer be called" seems more appropriate?
>
> Of course, if the native code stashes the function pointer in a variable somewhere, it would be possible for it to call the func pointer again. But what I meant is that, in principle, FFM should give you an exception when trying to call `call_me_back` again after the arena has been closed, or calling `callback_t::invoke` on a closed segment.

Yes, I had `can no longer be called` before, but switched to `should not be called` since it's technically more correct. I think `can not longer be called` makes more sense for the reader, in hindsight. Thanks

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

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

From jvernee at openjdk.org  Wed Apr 10 14:03:14 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Wed, 10 Apr 2024 14:03:14 GMT
Subject: RFR: Add jextract guide [v2]
In-Reply-To: <AeZHQmGpIoIHwRGfWj__qDBc1EeLHHI2U561zCQWDj8=.3f7769e6-17d7-4afa-aecc-f459923a15d9@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <AeZHQmGpIoIHwRGfWj__qDBc1EeLHHI2U561zCQWDj8=.3f7769e6-17d7-4afa-aecc-f459923a15d9@github.com>
Message-ID: <gtc8JRVjaOY6xe7J0bowFtsf9PqmtKoKKp2LoXDKtL0=.cb2ea86e-f245-4016-9988-cd917b91ac8f@github.com>

On Wed, 10 Apr 2024 09:58:01 GMT, Maurizio Cimadamore <mcimadamore at 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 at users.noreply.github.com>
>
> doc/GUIDE.md line 309:
> 
>> 307: ```
>> 308: 
>> 309: There's a getter and setter for each field of the struct (1), which takes a pointer to a struct
> 
> I see you didn't use bullet lists much, but I wonder if one would be helpful here instead of a single long para? Perhaps even a numbered list, where the number refers to the comment in the code?

I think a numbered list would be appropriate here

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

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

From jvernee at openjdk.org  Wed Apr 10 14:10:38 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Wed, 10 Apr 2024 14:10:38 GMT
Subject: RFR: Add jextract guide [v3]
In-Reply-To: <w6AAzGser9cwc6Gp61h1fhLdaTwlS_my8Q_sTAvyCgo=.4ab24817-c24c-4687-9097-ea2978b80305@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <w6AAzGser9cwc6Gp61h1fhLdaTwlS_my8Q_sTAvyCgo=.4ab24817-c24c-4687-9097-ea2978b80305@github.com>
Message-ID: <FvYUch7E_Ppv1dUVawP0X_qxNajB0XhFD6s8MoEgn4c=.8f7692fa-bb07-4860-b7e2-766c592e0b39@github.com>

On Wed, 10 Apr 2024 10:10:28 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   review comments
>
> doc/GUIDE.md line 486:
> 
>> 484: `callback_t` instance.
>> 485: 
>> 486: Jextract generates function pointer classes like the `callback_t` class for function
> 
> I know what you mean here - but I wonder if readers will get it w/o some kind of example.

I'll add some examples as well.

> doc/GUIDE.md line 665:
> 
>> 663: the elements we specify.
>> 664: 
>> 665: To allow for symbol filtering, `jextract` can generate a _dump_ of all the symbols
> 
> I noticed that in these sections, refrerences to `jextract` use a code block, whereas in the rest of the document they don't. I don't have a strong preference for one or the other, but we should make that consistent.

I'll just switch to the plain jextract, as that's a little easier on the eyes. (This section was copied from the readme)

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

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

From jvernee at openjdk.org  Wed Apr 10 14:10:37 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Wed, 10 Apr 2024 14:10:37 GMT
Subject: RFR: Add jextract guide [v3]
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <2u-FBZw62o3-IINa75bB2Vc9n2NVY-rcZhuHwh-CIpU=.435d3d52-2786-4475-b71f-bda083fab197@github.com>

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:

  review comments

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/231/files
  - new: https://git.openjdk.org/jextract/pull/231/files/15776ccc..87be3706

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=02
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=01-02

  Stats: 74 lines in 1 file changed: 24 ins; 1 del; 49 mod
  Patch: https://git.openjdk.org/jextract/pull/231.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/231/head:pull/231

PR: https://git.openjdk.org/jextract/pull/231

From jvernee at openjdk.org  Wed Apr 10 14:13:37 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Wed, 10 Apr 2024 14:13:37 GMT
Subject: RFR: Add jextract guide [v4]
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <dZKo97DkN9UfqM2bAMXt3dof_M_9aayhsK2sl5n7q1Q=.1a9ce54a-5aa0-416c-aa39-fda557822eac@github.com>

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:

  Split sentence

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/231/files
  - new: https://git.openjdk.org/jextract/pull/231/files/87be3706..5bf42921

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=03
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=02-03

  Stats: 12 lines in 1 file changed: 3 ins; 0 del; 9 mod
  Patch: https://git.openjdk.org/jextract/pull/231.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/231/head:pull/231

PR: https://git.openjdk.org/jextract/pull/231

From jvernee at openjdk.org  Wed Apr 10 14:16:13 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Wed, 10 Apr 2024 14:16:13 GMT
Subject: RFR: Add jextract guide [v4]
In-Reply-To: <FQ0gE9Z270cQUJEZSAwEV8RoOOa8-U6Qji25lgTKiy4=.61ab603a-b588-4ffe-b897-e74b385cd0f5@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <FQ0gE9Z270cQUJEZSAwEV8RoOOa8-U6Qji25lgTKiy4=.61ab603a-b588-4ffe-b897-e74b385cd0f5@github.com>
Message-ID: <jEcAafp2k9Vt6KKOZtqGWdZaLZlNhqNQuZmYx_Gm_64=.b9df9786-34b5-4f6f-b3f0-3daf3e3e68a6@github.com>

On Wed, 10 Apr 2024 10:25:15 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Split sentence
>
> doc/GUIDE.md line 808:
> 
>> 806: ### Additional clang options
>> 807: 
>> 808: Users can also specify additional clang compiler options, by creating a file named
> 
> Maybe here we should start by saying that `jextract` uses clang to parse C files. And if additional options need to be passed to the clang instance used by jextract...

I've added a leading sentence here in the latest version: `Jextract uses an embedded clang compiler (through libclang) to parse header files.`

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

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

From jvernee at openjdk.org  Wed Apr 10 14:34:25 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Wed, 10 Apr 2024 14:34:25 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:

  Phrasing
  
  Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/231/files
  - new: https://git.openjdk.org/jextract/pull/231/files/5bf42921..ab3465b2

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=04
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=03-04

  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jextract/pull/231.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/231/head:pull/231

PR: https://git.openjdk.org/jextract/pull/231

From mcimadamore at openjdk.org  Wed Apr 10 14:34:26 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 10 Apr 2024 14:34:26 GMT
Subject: RFR: Add jextract guide [v4]
In-Reply-To: <dZKo97DkN9UfqM2bAMXt3dof_M_9aayhsK2sl5n7q1Q=.1a9ce54a-5aa0-416c-aa39-fda557822eac@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <dZKo97DkN9UfqM2bAMXt3dof_M_9aayhsK2sl5n7q1Q=.1a9ce54a-5aa0-416c-aa39-fda557822eac@github.com>
Message-ID: <mNADT1IVnsV0q1-mrJgsR1ko_6PpwaUMQX-qCaUluZw=.cba11b2d-f0fb-43ae-9a39-3e7f8f2d8ed7@github.com>

On Wed, 10 Apr 2024 14:13:37 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Split sentence

Marked as reviewed by mcimadamore (Reviewer).

Great job! The guide reads great, and was long overdue :-)

doc/GUIDE.md line 407:

> 405: ### Function Pointers
> 406: 
> 407: Jextract will generate a separate class for each function pointer type found in the header

Suggestion:

Jextract generates a separate class for each function pointer type found in the header

doc/GUIDE.md line 505:

> 503: (such as struct fields or global variables):
> 504: 
> 505: ```c

thanks!

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

PR Review: https://git.openjdk.org/jextract/pull/231#pullrequestreview-1991864013
PR Comment: https://git.openjdk.org/jextract/pull/231#issuecomment-2047709012
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559545650
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559547444

From nlisker at openjdk.org  Wed Apr 10 14:45:12 2024
From: nlisker at openjdk.org (Nir Lisker)
Date: Wed, 10 Apr 2024 14:45:12 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
Message-ID: <XAwv452utKELJiW17RToEoaplyFZMYEGBGW6M1XqrrY=.0b5be964-d267-455d-9f0a-d98eed58be22@github.com>

On Wed, 10 Apr 2024 14:34:25 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Phrasing
>   
>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>

I'm still reviewing, please allow another day before merging.

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

PR Comment: https://git.openjdk.org/jextract/pull/231#issuecomment-2047749223

From jvernee at openjdk.org  Wed Apr 10 17:13:19 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Wed, 10 Apr 2024 17:13:19 GMT
Subject: RFR: Create pull request template
Message-ID: <40pQMS1R3dmon-0Cd9m4SbwBxjlWiQjLPq0cGYHqCkg=.5fbfeecf-792b-4faa-bcfe-b6af617f4979@github.com>

Create a pull request template. The text of the template will appear as the pull request description when creating a new pull request, and contains basic instructions on how to fill out the PR description, and how to test.

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

Commit messages:
 - Create PR template

Changes: https://git.openjdk.org/jextract/pull/233/files
  Webrev: https://webrevs.openjdk.org/?repo=jextract&pr=233&range=00
  Stats: 18 lines in 1 file changed: 18 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/jextract/pull/233.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/233/head:pull/233

PR: https://git.openjdk.org/jextract/pull/233

From jvernee at openjdk.org  Wed Apr 10 17:18:16 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Wed, 10 Apr 2024 17:18:16 GMT
Subject: RFR: Use compiler switch to filter out `__asm` statements on Windows
Message-ID: <z8swq3I0iKKyar2AObNMbOIrLbmiyxx01aqaMZLxczQ=.3ced5d67-1872-4ec8-9176-a25deb61b4ed@github.com>

A newly added test uses `__asm` statements which are not supported by MSVC. I failed to catch this during the review of that patch, and this result in a compilation failure on Windows in the most recent version of the code.

The test that needs this native code doesn't run on Windows any way, so I've removed all the Windows-isms from the native code, and instead just disabled compilation of the problematic code on Windows using a compiler switch.

Alternatively, we could modify the `CMakeLists.txt` file to disable building this particular library on Windows, if that's preferred.

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

Commit messages:
 - Use compiler switch to filter out __asm statements

Changes: https://git.openjdk.org/jextract/pull/234/files
  Webrev: https://webrevs.openjdk.org/?repo=jextract&pr=234&range=00
  Stats: 15 lines in 2 files changed: 2 ins; 4 del; 9 mod
  Patch: https://git.openjdk.org/jextract/pull/234.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/234/head:pull/234

PR: https://git.openjdk.org/jextract/pull/234

From mcimadamore at openjdk.org  Wed Apr 10 17:28:13 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 10 Apr 2024 17:28:13 GMT
Subject: RFR: Use compiler switch to filter out `__asm` statements on
 Windows
In-Reply-To: <z8swq3I0iKKyar2AObNMbOIrLbmiyxx01aqaMZLxczQ=.3ced5d67-1872-4ec8-9176-a25deb61b4ed@github.com>
References: <z8swq3I0iKKyar2AObNMbOIrLbmiyxx01aqaMZLxczQ=.3ced5d67-1872-4ec8-9176-a25deb61b4ed@github.com>
Message-ID: <JTQ4STF5Xclm7qDycmhnZUYfveSKuGBH-oVbuWyb9F0=.bd2118ec-84a2-4c20-8321-ced9c614cdc9@github.com>

On Wed, 10 Apr 2024 17:14:39 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> A newly added test uses `__asm` statements which are not supported by MSVC. I failed to catch this during the review of that patch, and this result in a compilation failure on Windows in the most recent version of the code.
> 
> The test that needs this native code doesn't run on Windows any way, so I've removed all the Windows-isms from the native code, and instead just disabled compilation of the problematic code on Windows using a compiler switch.
> 
> Alternatively, we could modify the `CMakeLists.txt` file to disable building this particular library on Windows, if that's preferred.

Thanks for checking. Question: why didn't the GHA tests failed?

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

Marked as reviewed by mcimadamore (Reviewer).

PR Review: https://git.openjdk.org/jextract/pull/234#pullrequestreview-1992306089

From mcimadamore at openjdk.org  Wed Apr 10 17:30:13 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 10 Apr 2024 17:30:13 GMT
Subject: RFR: Create pull request template
In-Reply-To: <40pQMS1R3dmon-0Cd9m4SbwBxjlWiQjLPq0cGYHqCkg=.5fbfeecf-792b-4faa-bcfe-b6af617f4979@github.com>
References: <40pQMS1R3dmon-0Cd9m4SbwBxjlWiQjLPq0cGYHqCkg=.5fbfeecf-792b-4faa-bcfe-b6af617f4979@github.com>
Message-ID: <DGGYUKSYUzpSFn1DrzbVaTHomC0amEnBGn6BlDLHpxY=.0ec3b492-4569-4220-9ae8-30ff100ab5e4@github.com>

On Wed, 10 Apr 2024 17:09:37 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Create a pull request template. The text of the template will appear as the pull request description when creating a new pull request, and contains basic instructions on how to fill out the PR description, and how to test.

Marked as reviewed by mcimadamore (Reviewer).

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

PR Review: https://git.openjdk.org/jextract/pull/233#pullrequestreview-1992308334

From jvernee at openjdk.org  Wed Apr 10 17:55:13 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Wed, 10 Apr 2024 17:55:13 GMT
Subject: Integrated: Create pull request template
In-Reply-To: <40pQMS1R3dmon-0Cd9m4SbwBxjlWiQjLPq0cGYHqCkg=.5fbfeecf-792b-4faa-bcfe-b6af617f4979@github.com>
References: <40pQMS1R3dmon-0Cd9m4SbwBxjlWiQjLPq0cGYHqCkg=.5fbfeecf-792b-4faa-bcfe-b6af617f4979@github.com>
Message-ID: <o8EuF5S9BBaZWKyOwlzlTfK3knUoPbQ6NiYPcEUwTGA=.68dd9bab-bb2b-44f9-b570-0b327f1c413d@github.com>

On Wed, 10 Apr 2024 17:09:37 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Create a pull request template. The text of the template will appear as the pull request description when creating a new pull request, and contains basic instructions on how to fill out the PR description, and how to test.

This pull request has now been integrated.

Changeset: d0429a56
Author:    Jorn Vernee <jvernee at openjdk.org>
URL:       https://git.openjdk.org/jextract/commit/d0429a56d98486aeafc11bfaf160b06635db009c
Stats:     18 lines in 1 file changed: 18 ins; 0 del; 0 mod

Create pull request template

Reviewed-by: mcimadamore

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

PR: https://git.openjdk.org/jextract/pull/233

From jvernee at openjdk.org  Wed Apr 10 17:56:09 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Wed, 10 Apr 2024 17:56:09 GMT
Subject: Integrated: Use compiler switch to filter out `__asm` statements on
 Windows
In-Reply-To: <z8swq3I0iKKyar2AObNMbOIrLbmiyxx01aqaMZLxczQ=.3ced5d67-1872-4ec8-9176-a25deb61b4ed@github.com>
References: <z8swq3I0iKKyar2AObNMbOIrLbmiyxx01aqaMZLxczQ=.3ced5d67-1872-4ec8-9176-a25deb61b4ed@github.com>
Message-ID: <sYJcjBZRD5GWMRGj8fQOda8igAVwb-quoDxPAxTe-c4=.f785be27-023f-4252-b6d8-6a56792038cd@github.com>

On Wed, 10 Apr 2024 17:14:39 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> A newly added test uses `__asm` statements which are not supported by MSVC. I failed to catch this during the review of that patch, and this result in a compilation failure on Windows in the most recent version of the code.
> 
> The test that needs this native code doesn't run on Windows any way, so I've removed all the Windows-isms from the native code, and instead just disabled compilation of the problematic code on Windows using a compiler switch.
> 
> Alternatively, we could modify the `CMakeLists.txt` file to disable building this particular library on Windows, if that's preferred.

This pull request has now been integrated.

Changeset: c7994e77
Author:    Jorn Vernee <jvernee at openjdk.org>
URL:       https://git.openjdk.org/jextract/commit/c7994e779535d61a4bd5a123269c3618f0794178
Stats:     15 lines in 2 files changed: 2 ins; 4 del; 9 mod

Use compiler switch to filter out `__asm` statements on Windows

Reviewed-by: mcimadamore

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

PR: https://git.openjdk.org/jextract/pull/234

From jvernee at openjdk.org  Wed Apr 10 17:56:09 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Wed, 10 Apr 2024 17:56:09 GMT
Subject: RFR: Use compiler switch to filter out `__asm` statements on
 Windows
In-Reply-To: <JTQ4STF5Xclm7qDycmhnZUYfveSKuGBH-oVbuWyb9F0=.bd2118ec-84a2-4c20-8321-ced9c614cdc9@github.com>
References: <z8swq3I0iKKyar2AObNMbOIrLbmiyxx01aqaMZLxczQ=.3ced5d67-1872-4ec8-9176-a25deb61b4ed@github.com>
 <JTQ4STF5Xclm7qDycmhnZUYfveSKuGBH-oVbuWyb9F0=.bd2118ec-84a2-4c20-8321-ced9c614cdc9@github.com>
Message-ID: <I6fVLWLtNqGYfHQ7VFREeBc9PzA1k1QVkT1ItcOZXq4=.11c4cd2d-4322-4faa-afc4-38f5195d232f@github.com>

On Wed, 10 Apr 2024 17:26:06 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> why didn't the GHA tests failed?

We only run GHA tests on Linux and Mac. AFAIK, building jtreg requires a full unix environment (I locally always have to use WSL). Perhaps it is possible to do that in GHA as well, but I haven't looked into that yet :)

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

PR Comment: https://git.openjdk.org/jextract/pull/234#issuecomment-2048141654

From jvernee at openjdk.org  Thu Apr 11 17:11:23 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Thu, 11 Apr 2024 17:11:23 GMT
Subject: RFR: Add Windows support in GitHub actions
Message-ID: <COowjL20P7kYsz1Sd69gS536-sxaQnpa2knH80aQnkM=.a0cfafcd-9db8-4ba4-bb78-adb5a5ba287b@github.com>

We currently don't run test in GitHub action on Windows. This can mean that a build failure on Windows may be missed (as seen recently). This PR adds support for running tests on Windows to the GitHub actions workflow.

Some notes about the changes:
- We can not build jtreg on Windows, so I've added a separate job which builds it on Ubuntu and then caches it. Then the main test job restores it from this cache. (FWIW, this cache is private/can not be downloaded outside of the actions)
- The `oracle-actions/setup-java` action we use gives us back a Windows path on Windows, which I don't think we can easily handle in bash, so I've created a Windows specific step for extracting the downloaded toolchain JDK
- Added caches also for LLVM/libclang and the toolchain JDK, so we don't have to download them all the time, and testing is faster.
- For that reason, I've added a step that creates a trimmed-down 'image' of the LLVM package with only the bits that we need, so that we can only cache those bits, instead of the entire LLVM package.

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

Commit messages:
 - use cache to restore jtreg in main job
 - rename step
 - Don'trebuild jtreg on cache hit
 - Trim down LLVM package for cache
 - cache jtreg too
 - remove actions files again
 - Try to use separate action scripts
 - Try add Windows support to GHA

Changes: https://git.openjdk.org/jextract/pull/235/files
  Webrev: https://webrevs.openjdk.org/?repo=jextract&pr=235&range=00
  Stats: 116 lines in 1 file changed: 78 ins; 7 del; 31 mod
  Patch: https://git.openjdk.org/jextract/pull/235.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/235/head:pull/235

PR: https://git.openjdk.org/jextract/pull/235

From mcimadamore at openjdk.org  Thu Apr 11 20:50:53 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Thu, 11 Apr 2024 20:50:53 GMT
Subject: RFR: Add Windows support in GitHub actions
In-Reply-To: <COowjL20P7kYsz1Sd69gS536-sxaQnpa2knH80aQnkM=.a0cfafcd-9db8-4ba4-bb78-adb5a5ba287b@github.com>
References: <COowjL20P7kYsz1Sd69gS536-sxaQnpa2knH80aQnkM=.a0cfafcd-9db8-4ba4-bb78-adb5a5ba287b@github.com>
Message-ID: <rTCfqlqPcR0EQyNbMx7uMUk9e7h7Xw5UnlgqjfzeeYw=.a24bab6b-09cc-4097-9b20-957f263fbe95@github.com>

On Thu, 11 Apr 2024 17:05:33 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> We currently don't run tests in GitHub actions on Windows. This can mean that a build failure on Windows may be missed (as seen recently). This PR adds support for running tests on Windows to the GitHub actions workflow.
> 
> Some notes about the changes:
> - We can not build jtreg on Windows, so I've added a separate job which builds it on Ubuntu and then caches it. Then the main test job restores it from this cache. (FWIW, this cache is private/can not be downloaded outside of the actions)
> - The `oracle-actions/setup-java` action we use gives us back a Windows path on Windows, which I don't think we can easily handle in bash, so I've created a Windows specific step for extracting the downloaded toolchain JDK
> - Added caches also for LLVM/libclang and the toolchain JDK, so we don't have to download them all the time, and testing is faster.
> - For that reason, I've added a step that creates a trimmed-down 'image' of the LLVM package with only the bits that we need, so that we can only cache those bits, instead of the entire LLVM package.

Marked as reviewed by mcimadamore (Reviewer).

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

PR Review: https://git.openjdk.org/jextract/pull/235#pullrequestreview-1995366725

From jvernee at openjdk.org  Fri Apr 12 02:07:50 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Fri, 12 Apr 2024 02:07:50 GMT
Subject: Integrated: Add Windows support in GitHub actions
In-Reply-To: <COowjL20P7kYsz1Sd69gS536-sxaQnpa2knH80aQnkM=.a0cfafcd-9db8-4ba4-bb78-adb5a5ba287b@github.com>
References: <COowjL20P7kYsz1Sd69gS536-sxaQnpa2knH80aQnkM=.a0cfafcd-9db8-4ba4-bb78-adb5a5ba287b@github.com>
Message-ID: <9BqPA4FFggQv_jjeikwhUAgct_CxVMvNbhqP6I6IRX4=.487b889f-f1d7-4f1e-ac33-e315db2ff6d8@github.com>

On Thu, 11 Apr 2024 17:05:33 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> We currently don't run tests in GitHub actions on Windows. This can mean that a build failure on Windows may be missed (as seen recently). This PR adds support for running tests on Windows to the GitHub actions workflow.
> 
> Some notes about the changes:
> - We can not build jtreg on Windows, so I've added a separate job which builds it on Ubuntu and then caches it. Then the main test job restores it from this cache. (FWIW, this cache is private/can not be downloaded outside of the actions)
> - The `oracle-actions/setup-java` action we use gives us back a Windows path on Windows, which I don't think we can easily handle in bash, so I've created a Windows specific step for extracting the downloaded toolchain JDK
> - Added caches also for LLVM/libclang and the toolchain JDK, so we don't have to download them all the time, and testing is faster.
> - For that reason, I've added a step that creates a trimmed-down 'image' of the LLVM package with only the bits that we need, so that we can only cache those bits, instead of the entire LLVM package.

This pull request has now been integrated.

Changeset: 8e68b17e
Author:    Jorn Vernee <jvernee at openjdk.org>
URL:       https://git.openjdk.org/jextract/commit/8e68b17e99b0e9e372840a3ab13edcd8fd9e32f4
Stats:     116 lines in 1 file changed: 78 ins; 7 del; 31 mod

Add Windows support in GitHub actions

Reviewed-by: mcimadamore

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

PR: https://git.openjdk.org/jextract/pull/235

From nlisker at openjdk.org  Fri Apr 12 19:41:56 2024
From: nlisker at openjdk.org (Nir Lisker)
Date: Fri, 12 Apr 2024 19:41:56 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
Message-ID: <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>

On Wed, 10 Apr 2024 14:34:25 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Phrasing
>   
>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>

An excellent guide. I read through all of it as someone who already used jextract and left some minor grammar comments that I found to help with the flow, but I would like to point out something more confusing with the structure.

The first part is about running jextract, including a short review of an example, followed by an explanation about loading libraries. It looks like this section explains the arguments/options passed to the tool, but it skips the discussion about the macros option (appears much later in Preprocessor Definitions) and other options.

The second part is about the code that is generated, but then there is an explanation about `--header-class-name` and `--target-package`, which should be part of the previous part. I would expect that by the time the user gets to learning about the generated Java code, they would know what commands generated it.

Also:
* Did you leave out "Bitfields" on purpose?
* Can a ToC be generated?

doc/GUIDE.md line 11:

> 9: archive of native functions and global variables. The user then has to look up the functions
> 10: they want to call using a `SymbolLookup`, and finally _link_ the functions by using the
> 11: `Linker::downcallHandle` method. Additionally, a client may need to create function pointer for

pointer -> pointers

doc/GUIDE.md line 18:

> 16: 
> 17: This guide shows how to run the jextract tool, and how to use the Java code that it generates.
> 18: The samples under [`samples`](samples) direcotry are also a good source of examples.

"under **the** samples directory"

doc/GUIDE.md line 29:

> 27: library called `mylib` stored at `/path/to/mylib` that has a directory `/path/to/mylib/include`
> 28: where the header files of that library are stored. And let's say that we have a shell open
> 29: in the root directory of the Java project we're working on, which has an `src` source

"a `src`" probably.

doc/GUIDE.md line 30:

> 28: where the header files of that library are stored. And let's say that we have a shell open
> 29: in the root directory of the Java project we're working on, which has an `src` source
> 30: directory corresponding to,the root package. A typical way to run jextract would be like

Space after the comma.

doc/GUIDE.md line 48:

> 46: - `--include-dir /path/to/mylib/include` specifies a header file search directory, which
> 47:    is used to find header files included through `#include` in the main header file.
> 48: - `--output src` specifies the root directory for the output. This matches to root package

"matches **the** root"

doc/GUIDE.md line 51:

> 49:   of the project's source directory.
> 50: - `--target-package org.jextract.mylib` specifies the target package to which the generated
> 51:   classes and interfaces will belong. (note that jextract will automatically create the

note -> Note

doc/GUIDE.md line 72:

> 70: to load libraries specified by `<libspec>`. If `<libspec>` denotes a library name, the
> 71: name is then mapped to a platform dependent name using [`System::mapLibraryName`](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/System.html#mapLibraryName(java.lang.String)).
> 72: This means for instance that on Linux, when specifying `--library mylib` the bindings will

Commas help here: "This means, for instance,"

doc/GUIDE.md line 75:

> 73: On Mac the relevant environment variable is `DYLD_LIBRARY_PATH`, and on Windows the variable is `PATH`.
> 74: Though, for the latter the overall library search mechanism is entirely different (described [here](https://learn.microsoft.com/en-us/windows/win32/dlls/dynamic-link-library-search-order)).
> 75: When using the HotSpot JVM, the `-Xlog:library` option can als be use to log where the JVM is trying to load a library from,

als -> also
use -> used

doc/GUIDE.md line 80:

> 78: and on Windows the variable is `PATH`. Though, for the latter the overall library search
> 79: mechanism is entirely different (described [here](https://learn.microsoft.com/en-us/windows/win32/dlls/dynamic-link-library-search-order)).
> 80: When using the HotSpot JVM, the `-Xlog:library` option can als be use to log where the JVM

als -> also
use -> used

doc/GUIDE.md line 84:

> 82: 
> 83: The `<libspec>` argument of the `--library` option can either be a library name, such as,
> 84: `mylib` which will, be mapped to a platform specific name using [`System::mapLibraryName`](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/System.html#mapLibraryName(java.lang.String)), or a path to a library file (either relative or

Comma after `mylib` instead of after `will`.

doc/GUIDE.md line 84:

> 82: 
> 83: The `<libspec>` argument of the `--library` option can either be a library name, such as,
> 84: `mylib` which will, be mapped to a platform specific name using [`System::mapLibraryName`](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/System.html#mapLibraryName(java.lang.String)), or a path to a library file (either relative or

This was already mentioned in the previous paragraph.

doc/GUIDE.md line 85:

> 83: The `<libspec>` argument of the `--library` option can either be a library name, such as,
> 84: `mylib` which will, be mapped to a platform specific name using [`System::mapLibraryName`](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/System.html#mapLibraryName(java.lang.String)), or a path to a library file (either relative or
> 85: absolute) if `<libspec>` is prefixed with the `:` character, such as `mylib.dll`.

Shouldn't the example then be `:mylib.dll`?

doc/GUIDE.md line 106:

> 104: some examples of how to use the generated Java code.
> 105: 
> 106: Most of the code that jextract generates will be available through a single class. By default

"By default,"

doc/GUIDE.md line 126:

> 124: ```
> 125: 
> 126: Where `org.mypackage` is the package into which jextract put the generates source files

"puts the generated"

doc/GUIDE.md line 134:

> 132: builtin C types.
> 133: 
> 134: The latter import statement imports all the other classes the jextract generates, which

"that jextract generates"

doc/GUIDE.md line 135:

> 133: 
> 134: The latter import statement imports all the other classes the jextract generates, which
> 135: includes: classes representing structs or unions, function types, and struct or union

includes -> include

doc/GUIDE.md line 164:

> 162: `short,` `int`, `long long`, `float`, `double` `long`, and `long double`. Additionally,
> 163: there is a `C_POINTER` layout which represents the layout for any C pointer type (such as
> 164: `T*`). Note that these layouts are platform dependent, depending on the platform that

"platform dependent, depending on the platform"

This is somewhat redundant. Just "these layouts depend on" maybe, or some other phrasing.

doc/GUIDE.md line 167:

> 165: jextract runs on. For instance, since these constants were generated on Windows, the
> 166: `long` type has the same layout as the Java `int` type, indicating a 32-bit value, and the
> 167: `long double` type has the same layout as the Java `double` type. (note that the latter is

note -> Note

doc/GUIDE.md line 181:

> 179: ```
> 180: 
> 181: Jextract will generate the following set of methods for this function, in the main header

function, -> function

doc/GUIDE.md line 185:

> 183: 
> 184: ```java
> 185: // mylib_h.java

Assuming the class name options wasn't specified (if you want to mention that, though not important).

doc/GUIDE.md line 197:

> 195: call the C function (1). Besides that, there are also several accessors that return
> 196: additional meta-data for the method: the function's address (2), the function descriptor
> 197: (3), and the method handle returned by the FFM linker (4), which is used to implement the

I would add inline links for convenience, like:  `[function's address](MemorySegment)`, `[function descriptor](FunctionDescriptor)` and `(method handle)[MethodHandle]`

doc/GUIDE.md line 200:

> 198: static wrapper method (1).
> 199: 
> 200: The parameter types and return type of this method depend on the carrier types of the

Is the reader supposed to know what a "carrier type" is? Can a link be given to an explanation if one exists in FFM maybe?

doc/GUIDE.md line 211:

> 209: // mylib.h
> 210: 
> 211: int bar;

Maybe mention what happens if the definition includes an assignment, `int bar = 4;`, if it matters.

doc/GUIDE.md line 269:

> 267: not supported by jextract. For function-like macros, alternatives include re-writing the
> 268: code inside the macro in Java, using the FFM API, or writing a small C library which wraps
> 269: the function-like macro in a proper exported C function, that can then be linked against

"function," -> "function"

doc/GUIDE.md line 348:

> 346: 
> 347: For working with arrays of structs, we can use the `allocateArray` method which accepts an
> 348: additional element count, indicating the length of the array:

Comma before "which" instead of after "count".

doc/GUIDE.md line 358:

> 356: 
> 357:     for (int i = 0; i < arrLen; i++) {
> 358:         MemorySegment element = Point.asSlice(point, i);

Never used this method, but I assume it should be `asSlice(points, i)`.

doc/GUIDE.md line 369:

> 367: In the above example, the `asSlice` method is used to _slice_ out a section of
> 368: the array, which corresponds to a single `Point` struct element. This method
> 369: can be used to access individual elements of the `points` array, when given

"array," -> "array"

doc/GUIDE.md line 438:

> 436: we received from native code.
> 437: 
> 438: For instance, let's say we have a function that accepts an instance of the `callback_t`

For clarity, I would say "have a native function".

doc/GUIDE.md line 456:

> 454: try (Arena arena = Arena.ofConfined()) {
> 455: ? ? MemorySegment cb = callback_t.allocate((a, b) -> a * b, arena);
> 456: ? ? int result = call_me_back(cb);

Where is `call_me_back` defined?

doc/GUIDE.md line 468:

> 466: can no longer be called).
> 467: 
> 468: Additionally, we can using the `callback_t::invoke` method invoke an instance of

using -> use

doc/GUIDE.md line 485:

> 483: 
> 484: The `get_callback` function returns an instance of `callback_t`, which is a function pointer
> 485: pointing to the native `mult` function. We can call `callback_t` instance that `get_callback()`

"call **the** `callback_t` instance"

doc/GUIDE.md line 486:

> 484: The `get_callback` function returns an instance of `callback_t`, which is a function pointer
> 485: pointing to the native `mult` function. We can call `callback_t` instance that `get_callback()`
> 486: return in Java using the `invoke` method in the `callback_t` class that jextract generates

return -> returns

doc/GUIDE.md line 534:

> 532: ```
> 533: 
> 534: Jextract doesn't generates a regular method, but a _class_, which represents the invoker:

generates -> generate

doc/GUIDE.md line 576:

> 574: ### Typedefs
> 575: 
> 576: As mentioned before: typedefs are either translated as a `static final` memory layout fields

before: -> before,

doc/GUIDE.md line 603:

> 601: ```
> 602: 
> 603: The `MyPoint` `typedef` on the other hand is a typedef for a struct, so it is translated

"`typedef` on the other hand" -> "`typedef`, on the other hand,"

doc/GUIDE.md line 618:

> 616: 
> 617: C allows variable declarations to have an inline anonymous type. Jextract handles in
> 618: particular cases where a struct's field has an inline type specially. For instance, if we

"Jextract handles in particular cases where a struct's field has an inline type specially."

I don't understand this sentence. Does Jextract handle nested types only when a struct's field has an inline type?

doc/GUIDE.md line 634:

> 632: 
> 633: Jextract generates a _nested_ struct and function pointer class for the `bar` and `cb`
> 634: fields, _inside of_ the class it generates for the `Foo` struct itself:

fields, -> fields

doc/GUIDE.md line 713:

> 711: 
> 712: The include options in this file can then be edited down to a set of symbols that is
> 713: desired, for instance using other command line tools such as `grep` or `Select-String`,

instance -> instance,

doc/GUIDE.md line 800:

> 798: 
> 799: The value of these macros also affects the behavior of jextract. Therefore, jextract
> 800: supports setting macro values on the command line using the `-D` or

Perhaps mentioning the distinctions between these macros and the ones described in the Constants section more specifically will be helpful?

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

PR Review: https://git.openjdk.org/jextract/pull/231#pullrequestreview-1989727538
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562492438
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562494228
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562499511
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562495661
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562498454
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562500829
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562503617
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1558074831
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562505421
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562506125
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562510865
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562511595
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562515695
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562517992
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562519931
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562520377
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562532950
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562534017
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562536552
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562538150
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562544444
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562548168
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562583132
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562620372
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562631106
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562634105
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1562635428
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1563001201
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1563006011
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1563008874
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1563038152
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1563038500
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1563049288
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1563054342
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1563069603
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1563074084
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1563075034
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1563083141
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1563096318

From nlisker at openjdk.org  Fri Apr 12 19:41:56 2024
From: nlisker at openjdk.org (Nir Lisker)
Date: Fri, 12 Apr 2024 19:41:56 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <YaUFXfKSmF5-yhUClvfE1FKHiqfezPnXWuGcB8hKYUw=.1312dd57-3a1e-46fa-bb16-b08055030a33@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <Lr1vJvEgTEu559aJf-Tr-0RgKWQMPUR6jmocZxaurZc=.159fe14c-19e7-4d55-bfce-bf640ee379cb@github.com>
 <YaUFXfKSmF5-yhUClvfE1FKHiqfezPnXWuGcB8hKYUw=.1312dd57-3a1e-46fa-bb16-b08055030a33@github.com>
Message-ID: <SUsjEWLFrfocqo5-nhKvxCN0WPnS0GZr7mNdm3ki3tA=.acd7f594-cea6-42b8-b9ae-4b53f66741de@github.com>

On Tue, 9 Apr 2024 20:15:18 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> doc/GUIDE.md line 8:
>> 
>>> 6: 
>>> 7: Interacting with native C code through the FFM API works
>>> 8: by loading a native library (e.g. a `.so`/`.dll`/`.dylib` file), which is essentially an
>> 
>> Comma after `e.g.`.
>
> You mean add a comma like `e.g., ...`?

Yes.

I meant to put these comment in a longer review, but misclicked. Some remarks are more substantial than others.

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

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

From mcimadamore at openjdk.org  Fri Apr 12 21:13:52 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Fri, 12 Apr 2024 21:13:52 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
 <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
Message-ID: <P6vqDa5jN2J2cC066b7_Rl3vJO88OXh9xuGhN6fP5GE=.0f143929-6452-42af-b413-515d80d6d6ac@github.com>

On Fri, 12 Apr 2024 12:49:39 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Phrasing
>>   
>>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>
> doc/GUIDE.md line 84:
> 
>> 82: 
>> 83: The `<libspec>` argument of the `--library` option can either be a library name, such as,
>> 84: `mylib` which will, be mapped to a platform specific name using [`System::mapLibraryName`](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/System.html#mapLibraryName(java.lang.String)), or a path to a library file (either relative or
> 
> Comma after `mylib` instead of after `will`.

I'd also drop the comma after `such as`

> doc/GUIDE.md line 134:
> 
>> 132: builtin C types.
>> 133: 
>> 134: The latter import statement imports all the other classes the jextract generates, which
> 
> "that jextract generates"

or, `generated by jextract`

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

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

From mcimadamore at openjdk.org  Fri Apr 12 21:18:54 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Fri, 12 Apr 2024 21:18:54 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
 <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
Message-ID: <c1wKp-wkt5zzESCUHgcO_GuBLW3tU7VnrvC9oBwWoSY=.4eb180b3-ee2a-4286-a075-1d8edf5fa02a@github.com>

On Fri, 12 Apr 2024 19:39:26 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

> Did you leave out "Bitfields" on purpose?

Jextract does not support bitfields (due to deficiencies in the libclang API). That's why there's no section for them :-)

> doc/GUIDE.md line 29:
> 
>> 27: library called `mylib` stored at `/path/to/mylib` that has a directory `/path/to/mylib/include`
>> 28: where the header files of that library are stored. And let's say that we have a shell open
>> 29: in the root directory of the Java project we're working on, which has an `src` source
> 
> "a `src`" probably.

I believe this was discussed here:
https://github.com/openjdk/jextract/pull/231#discussion_r1559141069

> doc/GUIDE.md line 348:
> 
>> 346: 
>> 347: For working with arrays of structs, we can use the `allocateArray` method which accepts an
>> 348: additional element count, indicating the length of the array:
> 
> Comma before "which" instead of after "count".

I find the way it's currently written fine (and better than the suggested one)

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

PR Comment: https://git.openjdk.org/jextract/pull/231#issuecomment-2052541652
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1563207432
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1563205742

From nlisker at openjdk.org  Sat Apr 13 05:38:53 2024
From: nlisker at openjdk.org (Nir Lisker)
Date: Sat, 13 Apr 2024 05:38:53 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <c1wKp-wkt5zzESCUHgcO_GuBLW3tU7VnrvC9oBwWoSY=.4eb180b3-ee2a-4286-a075-1d8edf5fa02a@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
 <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
 <c1wKp-wkt5zzESCUHgcO_GuBLW3tU7VnrvC9oBwWoSY=.4eb180b3-ee2a-4286-a075-1d8edf5fa02a@github.com>
Message-ID: <cXzv1GT5E09MwMoOKse8yUnMnUq-1BteIrh00qikNSg=.cf4d087c-6507-461d-994e-4c5f0499c22e@github.com>

On Fri, 12 Apr 2024 21:15:08 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> > Did you leave out "Bitfields" on purpose?
> 
> Jextract does not support bitfields (due to deficiencies in the libclang API). That's why there's no section for them :-)

Then maybe mention that :)

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

PR Comment: https://git.openjdk.org/jextract/pull/231#issuecomment-2053511126

From nlisker at openjdk.org  Sun Apr 14 20:55:51 2024
From: nlisker at openjdk.org (Nir Lisker)
Date: Sun, 14 Apr 2024 20:55:51 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
Message-ID: <Ntp232z0RdQon0OVOf97-v-wU5goHW258E4Qs1EMTtE=.f2d873a2-bff2-4363-9b68-101e38eb073f@github.com>

On Wed, 10 Apr 2024 14:34:25 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Phrasing
>   
>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>

doc/GUIDE.md line 757:

> 755: 
> 756: To enable the tracing support, just pass the `-Djextract.trace.downcalls=true` flag to the
> 757: launcher used to start the application. Below we show an excerpt of the output when

I would mention that this is passed as a VM argument, not as a program argument.

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

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

From jvernee at openjdk.org  Mon Apr 15 12:38:54 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 12:38:54 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
 <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
Message-ID: <Hbn44YWxkhfzFnGplCc_Ja9bqpe8W7L7KtKj08oejl4=.36bcc7a1-1748-487d-9b28-059c1abfe24f@github.com>

On Fri, 12 Apr 2024 19:39:26 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

> The first part is about running jextract, including a short review of an example, followed by an explanation about loading libraries. It looks like this section explains the arguments/options passed to the tool, but it skips the discussion about the macros option (appears much later in Preprocessor Definitions) and other options.
> 
> The second part is about the code that is generated, but then there is an explanation about `--header-class-name` and `--target-package`, which should be part of the previous part. I would expect that by the time the user gets to learning about the generated Java code, they would know what commands generated it.

Yes. The intent of this was to not bog down the intro with information that is not used that often, so people can get started quickly. But, in hindsight, I think it is better to just put all the discussion about command line arguments in 1 place. (Especially some of the info in the section about `-D` is important to get jextract to 'work'). I'll re-arrange the sections a bit.

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

PR Comment: https://git.openjdk.org/jextract/pull/231#issuecomment-2056751066

From jvernee at openjdk.org  Mon Apr 15 13:04:00 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 13:04:00 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
 <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
Message-ID: <IHF_qgv7NqL0pQK7Q5NKe40yAkNp7xGKf6gG7vJLO7I=.6658ec0c-1889-4539-933d-6a1422b7aa32@github.com>

On Fri, 12 Apr 2024 13:49:21 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Phrasing
>>   
>>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>
> doc/GUIDE.md line 211:
> 
>> 209: // mylib.h
>> 210: 
>> 211: int bar;
> 
> Maybe mention what happens if the definition includes an assignment, `int bar = 4;`, if it matters.

For jextract it doesn't matter

> doc/GUIDE.md line 358:
> 
>> 356: 
>> 357:     for (int i = 0; i < arrLen; i++) {
>> 358:         MemorySegment element = Point.asSlice(point, i);
> 
> Never used this method, but I assume it should be `asSlice(points, i)`.

Good catch!

> doc/GUIDE.md line 456:
> 
>> 454: try (Arena arena = Arena.ofConfined()) {
>> 455: ? ? MemorySegment cb = callback_t.allocate((a, b) -> a * b, arena);
>> 456: ? ? int result = call_me_back(cb);
> 
> Where is `call_me_back` defined?

It's defined in the C file in the snippet above.

> doc/GUIDE.md line 618:
> 
>> 616: 
>> 617: C allows variable declarations to have an inline anonymous type. Jextract handles in
>> 618: particular cases where a struct's field has an inline type specially. For instance, if we
> 
> "Jextract handles in particular cases where a struct's field has an inline type specially."
> 
> I don't understand this sentence. Does Jextract handle nested types only when a struct's field has an inline type?

C doesn't allow other kinds of nested types, so yeah

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565748513
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565750938
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565752183
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565755721

From jvernee at openjdk.org  Mon Apr 15 13:04:00 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 13:04:00 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <IHF_qgv7NqL0pQK7Q5NKe40yAkNp7xGKf6gG7vJLO7I=.6658ec0c-1889-4539-933d-6a1422b7aa32@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
 <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
 <IHF_qgv7NqL0pQK7Q5NKe40yAkNp7xGKf6gG7vJLO7I=.6658ec0c-1889-4539-933d-6a1422b7aa32@github.com>
Message-ID: <4wtAIOLI28AO2c7mv2LfA4f9XtPVojA_hrcikXpyB4E=.c21fa5f1-6ef6-4af1-bde7-f57579bcb462@github.com>

On Mon, 15 Apr 2024 12:59:53 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> doc/GUIDE.md line 618:
>> 
>>> 616: 
>>> 617: C allows variable declarations to have an inline anonymous type. Jextract handles in
>>> 618: particular cases where a struct's field has an inline type specially. For instance, if we
>> 
>> "Jextract handles in particular cases where a struct's field has an inline type specially."
>> 
>> I don't understand this sentence. Does Jextract handle nested types only when a struct's field has an inline type?
>
> C doesn't allow other kinds of nested types, so yeah

I'll just remove the 'Jextract handles in particular cases where a struct's field has an inline type specially.' part here

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

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

From jvernee at openjdk.org  Mon Apr 15 13:07:55 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 13:07:55 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
 <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
Message-ID: <ajgaWXhQWhykLbNsz2uA2Ybi8J4nnRNgfgaxBC_lg_k=.99ded39e-faa8-4cb6-910b-92b9d355a192@github.com>

On Fri, 12 Apr 2024 19:38:20 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Phrasing
>>   
>>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>
> doc/GUIDE.md line 800:
> 
>> 798: 
>> 799: The value of these macros also affects the behavior of jextract. Therefore, jextract
>> 800: supports setting macro values on the command line using the `-D` or
> 
> Perhaps mentioning the distinctions between these macros and the ones described in the Constants section more specifically will be helpful?

Hmm, not sure what to say. There are no real distinctions, but jextract only generates an accessor if a macro is defined in the header files, not if it is only set on the command line with `-D`. (I'll add that at least)

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

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

From jvernee at openjdk.org  Mon Apr 15 13:11:01 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 13:11:01 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
 <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
Message-ID: <vEMKVc8Ta-lOeLHcA4ixieolo4VTBGEHNkniEnrLVu0=.5cdd34a5-ee45-44e5-81b9-39c07884aaec@github.com>

On Fri, 12 Apr 2024 19:39:26 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

> Can a ToC be generated?

It should be generated automatically by GitHub

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

PR Comment: https://git.openjdk.org/jextract/pull/231#issuecomment-2056814832

From jvernee at openjdk.org  Mon Apr 15 13:25:12 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 13:25:12 GMT
Subject: RFR: Add jextract guide [v6]
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <bePF6GjJDM37WgE7nfq_8R1jxyJYXJmXwOjmKl46Vzc=.0ed30ccb-b91f-4684-8427-8ccaabd44bf4@github.com>

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:

  review comments

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/231/files
  - new: https://git.openjdk.org/jextract/pull/231/files/ab3465b2..b9218138

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=05
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=04-05

  Stats: 159 lines in 1 file changed: 73 ins; 41 del; 45 mod
  Patch: https://git.openjdk.org/jextract/pull/231.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/231/head:pull/231

PR: https://git.openjdk.org/jextract/pull/231

From jvernee at openjdk.org  Mon Apr 15 13:25:12 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 13:25:12 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <cXzv1GT5E09MwMoOKse8yUnMnUq-1BteIrh00qikNSg=.cf4d087c-6507-461d-994e-4c5f0499c22e@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
 <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
 <c1wKp-wkt5zzESCUHgcO_GuBLW3tU7VnrvC9oBwWoSY=.4eb180b3-ee2a-4286-a075-1d8edf5fa02a@github.com>
 <cXzv1GT5E09MwMoOKse8yUnMnUq-1BteIrh00qikNSg=.cf4d087c-6507-461d-994e-4c5f0499c22e@github.com>
Message-ID: <yvCPtu30_A_iJ5SJuH8d49oaYN6BK2fWQTP2e4Waz9s=.5c20b631-dd8c-4bef-afc7-ca6d06832532@github.com>

On Sat, 13 Apr 2024 05:36:09 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

> > > Did you leave out "Bitfields" on purpose?
> > 
> > 
> > Jextract does not support bitfields (due to deficiencies in the libclang API). That's why there's no section for them :-)
> 
> Then maybe mention that :)

I've added a section about unsupported features. (also to explain some of the warnings a user may see)

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

PR Comment: https://git.openjdk.org/jextract/pull/231#issuecomment-2056835517

From jvernee at openjdk.org  Mon Apr 15 13:25:12 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 13:25:12 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
 <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
Message-ID: <dAzxOV2Vi5hYauf1usDC_8HHc7VDIa2uXZ4ehFwu5o8=.b1b77250-4032-4ad6-90a2-241875be3413@github.com>

On Fri, 12 Apr 2024 13:16:16 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Phrasing
>>   
>>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>
> doc/GUIDE.md line 185:
> 
>> 183: 
>> 184: ```java
>> 185: // mylib_h.java
> 
> Assuming the class name options wasn't specified (if you want to mention that, though not important).

Don't think it's that important to mention. The comment is mostly there for consistency, as the text above already says that this is the class that jextract generates.

> doc/GUIDE.md line 200:
> 
>> 198: static wrapper method (1).
>> 199: 
>> 200: The parameter types and return type of this method depend on the carrier types of the
> 
> Is the reader supposed to know what a "carrier type" is? Can a link be given to an explanation if one exists in FFM maybe?

'carrier type` is indeed an FFM concept. I've added a link to `FunctionDescriptor::toMethodType` which explains how these are derived.

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

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

From nlisker at openjdk.org  Mon Apr 15 13:25:13 2024
From: nlisker at openjdk.org (Nir Lisker)
Date: Mon, 15 Apr 2024 13:25:13 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <IHF_qgv7NqL0pQK7Q5NKe40yAkNp7xGKf6gG7vJLO7I=.6658ec0c-1889-4539-933d-6a1422b7aa32@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
 <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
 <IHF_qgv7NqL0pQK7Q5NKe40yAkNp7xGKf6gG7vJLO7I=.6658ec0c-1889-4539-933d-6a1422b7aa32@github.com>
Message-ID: <HHSyqylnbUZ1ecEQC7GN4Go7qdFrg0x_UoMp184FBx8=.7eeccf7e-8642-4827-819b-8b377e6ad745@github.com>

On Mon, 15 Apr 2024 12:57:22 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> doc/GUIDE.md line 456:
>> 
>>> 454: try (Arena arena = Arena.ofConfined()) {
>>> 455: ? ? MemorySegment cb = callback_t.allocate((a, b) -> a * b, arena);
>>> 456: ? ? int result = call_me_back(cb);
>> 
>> Where is `call_me_back` defined?
>
> It's defined in the C file in the snippet above.

But we can't call the c function directly. Are there more java bindings that jextract generates?

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

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

From jvernee at openjdk.org  Mon Apr 15 13:25:13 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 13:25:13 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <HHSyqylnbUZ1ecEQC7GN4Go7qdFrg0x_UoMp184FBx8=.7eeccf7e-8642-4827-819b-8b377e6ad745@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
 <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
 <IHF_qgv7NqL0pQK7Q5NKe40yAkNp7xGKf6gG7vJLO7I=.6658ec0c-1889-4539-933d-6a1422b7aa32@github.com>
 <HHSyqylnbUZ1ecEQC7GN4Go7qdFrg0x_UoMp184FBx8=.7eeccf7e-8642-4827-819b-8b377e6ad745@github.com>
Message-ID: <7xCiGlW5c7wExsaeQ_ib9AzP3JHQ8Pleu897BqNyJfQ=.a2cc00af-bd59-466b-b565-20c98532e0a5@github.com>

On Mon, 15 Apr 2024 13:07:34 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> It's defined in the C file in the snippet above.
>
> But we can't call the c function directly. Are there more java bindings that jextract generates?

Sorry, the example assumes that that the `call_me_back` function is also defined in the header file that jextract extracted, so a Java method would be generated for it.

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

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

From jvernee at openjdk.org  Mon Apr 15 13:46:08 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 13:46:08 GMT
Subject: RFR: Add jextract guide [v7]
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <FP-n7rvjSeA0a15IK7YirsOriMNAKdmnleKnBYsEFg0=.660ed39d-6908-4992-940a-5155196dc49a@github.com>

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

Jorn Vernee has updated the pull request incrementally with two additional commits since the last revision:

 - Update doc/GUIDE.md
   
   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
 - add note about call_me_back needing to be present in header file as well

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/231/files
  - new: https://git.openjdk.org/jextract/pull/231/files/b9218138..a9e7bb8b

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=06
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=05-06

  Stats: 3 lines in 1 file changed: 1 ins; 0 del; 2 mod
  Patch: https://git.openjdk.org/jextract/pull/231.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/231/head:pull/231

PR: https://git.openjdk.org/jextract/pull/231

From mcimadamore at openjdk.org  Mon Apr 15 13:46:09 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Mon, 15 Apr 2024 13:46:09 GMT
Subject: RFR: Add jextract guide [v6]
In-Reply-To: <bePF6GjJDM37WgE7nfq_8R1jxyJYXJmXwOjmKl46Vzc=.0ed30ccb-b91f-4684-8427-8ccaabd44bf4@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <bePF6GjJDM37WgE7nfq_8R1jxyJYXJmXwOjmKl46Vzc=.0ed30ccb-b91f-4684-8427-8ccaabd44bf4@github.com>
Message-ID: <m0Cey1wj33xqxWXBIzDS2KNtLXqVwhQjaajIlqGICGg=.28e15c7c-59db-4558-b73a-186858c08a18@github.com>

On Mon, 15 Apr 2024 13:25:12 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
> 
>   review comments

doc/GUIDE.md line 79:

> 77: [libclang](https://clang.llvm.org/docs/LibClang.html) native library in order to parse C sources).
> 78: 
> 79: ### Preprocessor Definitions

IMHO both this and the following section is not important enough to appear so early in the document. If we went straight to "Using The Code Generated By Jextract" we would not lose anything - then after that section, we can provide more details about various aspects/options.

doc/GUIDE.md line 147:

> 145: some examples of how to use the generated Java code.
> 146: 
> 147: Most of the methods that jextract generates are `static`, and are designed to be imported

Uhm - I think the paras you moved fitted nicely in this introductory section

doc/GUIDE.md line 226:

> 224: First and foremost, there is a static wrapper method that is generated that can be used to
> 225: call the C function (1). Besides that, there are also several accessors that return
> 226: additional meta-data for the method: the function's address, represented as a

Should we use a numbered list here too?

doc/GUIDE.md line 306:

> 304: 
> 305: Note that for macros, jextract only generates an accessor when it sees a macro definition,
> 306: like the one in the example, in the header files it parses. When a macro is only defined

Suggestion:

like the one in the example, in the header files it parses. When a macro is defined

doc/GUIDE.md line 307:

> 305: Note that for macros, jextract only generates an accessor when it sees a macro definition,
> 306: like the one in the example, in the header files it parses. When a macro is only defined
> 307: using `-D` on the command line, not accessor will be generated.

Suggestion:

using `-D` on the command line, no accessor will be generated.

doc/GUIDE.md line 848:

> 846: ## Unsupported Features
> 847: 
> 848: There are several elements for which jextract can not generate bindings:

element seems a bit vague, maybe "C program elements" could be better, although in this cases I suppose most developers will think about the term "features". Consider just having a bullet list and skip the first statement (after all, the title says it all). Note also the list is provided here:
https://jdk.java.net/jextract/
(maybe we should drop it from there in the future, to avoid duplication?)

doc/GUIDE.md line 869:

> 867:   WARNING: Skipping Foo (type Declared(Foo) is not supported)
> 868:   ```
> 869: 

Bitfields missing?
Also, support for primitive types > 64 bits.

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565821418
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565806681
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565809259
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565810496
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565810263
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565815548
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565816332

From jvernee at openjdk.org  Mon Apr 15 13:46:09 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 13:46:09 GMT
Subject: RFR: Add jextract guide [v6]
In-Reply-To: <m0Cey1wj33xqxWXBIzDS2KNtLXqVwhQjaajIlqGICGg=.28e15c7c-59db-4558-b73a-186858c08a18@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <bePF6GjJDM37WgE7nfq_8R1jxyJYXJmXwOjmKl46Vzc=.0ed30ccb-b91f-4684-8427-8ccaabd44bf4@github.com>
 <m0Cey1wj33xqxWXBIzDS2KNtLXqVwhQjaajIlqGICGg=.28e15c7c-59db-4558-b73a-186858c08a18@github.com>
Message-ID: <10I-po0ckrQYYl9M4VpnDgjDYFp6WEjU5AGvrAOxieQ=.81e6433f-caf8-4bb5-9fd6-57c54146f2bc@github.com>

On Mon, 15 Apr 2024 13:32:21 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   review comments
>
> doc/GUIDE.md line 147:
> 
>> 145: some examples of how to use the generated Java code.
>> 146: 
>> 147: Most of the methods that jextract generates are `static`, and are designed to be imported
> 
> Uhm - I think the paras you moved fitted nicely in this introductory section

I think they could go in either section? But, this way, we can discuss the `--header-class-name` option in the section about running, which I think makes more sense.

> doc/GUIDE.md line 226:
> 
>> 224: First and foremost, there is a static wrapper method that is generated that can be used to
>> 225: call the C function (1). Besides that, there are also several accessors that return
>> 226: additional meta-data for the method: the function's address, represented as a
> 
> Should we use a numbered list here too?

I don't think it's possible to start a markdown list at `2`, but I will try

> doc/GUIDE.md line 306:
> 
>> 304: 
>> 305: Note that for macros, jextract only generates an accessor when it sees a macro definition,
>> 306: like the one in the example, in the header files it parses. When a macro is only defined
> 
> Suggestion:
> 
> like the one in the example, in the header files it parses. When a macro is defined

`only` is relevant here. If a macro is defined using `#define` _and_ on the command line, jextract will generate an accessor.

> doc/GUIDE.md line 869:
> 
>> 867:   WARNING: Skipping Foo (type Declared(Foo) is not supported)
>> 868:   ```
>> 869: 
> 
> Bitfields missing?
> Also, support for primitive types > 64 bits.

Bitfields is there. I'll add an item for types > 64 bits

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565813726
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565814932
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565816756
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565820708

From nlisker at openjdk.org  Mon Apr 15 13:46:10 2024
From: nlisker at openjdk.org (Nir Lisker)
Date: Mon, 15 Apr 2024 13:46:10 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <7xCiGlW5c7wExsaeQ_ib9AzP3JHQ8Pleu897BqNyJfQ=.a2cc00af-bd59-466b-b565-20c98532e0a5@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
 <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
 <IHF_qgv7NqL0pQK7Q5NKe40yAkNp7xGKf6gG7vJLO7I=.6658ec0c-1889-4539-933d-6a1422b7aa32@github.com>
 <HHSyqylnbUZ1ecEQC7GN4Go7qdFrg0x_UoMp184FBx8=.7eeccf7e-8642-4827-819b-8b377e6ad745@github.com>
 <7xCiGlW5c7wExsaeQ_ib9AzP3JHQ8Pleu897BqNyJfQ=.a2cc00af-bd59-466b-b565-20c98532e0a5@github.com>
Message-ID: <XbM1rOz1D1M3ckA__FjaNT3-DxBK-F1yKdY1KDI4Xzs=.becfe980-60ea-48a8-b9e9-a04aff4cce6a@github.com>

On Mon, 15 Apr 2024 13:19:45 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> But we can't call the c function directly. Are there more java bindings that jextract generates?
>
> Sorry, the example assumes that that the `call_me_back` function is also defined in the header file that jextract extracted, so a Java method would be generated for it.

I would mentioned that. After all, this tool is meant to save Java developers from knowing the intricacies of the native language.

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

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

From mcimadamore at openjdk.org  Mon Apr 15 13:46:10 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Mon, 15 Apr 2024 13:46:10 GMT
Subject: RFR: Add jextract guide [v6]
In-Reply-To: <10I-po0ckrQYYl9M4VpnDgjDYFp6WEjU5AGvrAOxieQ=.81e6433f-caf8-4bb5-9fd6-57c54146f2bc@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <bePF6GjJDM37WgE7nfq_8R1jxyJYXJmXwOjmKl46Vzc=.0ed30ccb-b91f-4684-8427-8ccaabd44bf4@github.com>
 <m0Cey1wj33xqxWXBIzDS2KNtLXqVwhQjaajIlqGICGg=.28e15c7c-59db-4558-b73a-186858c08a18@github.com>
 <10I-po0ckrQYYl9M4VpnDgjDYFp6WEjU5AGvrAOxieQ=.81e6433f-caf8-4bb5-9fd6-57c54146f2bc@github.com>
Message-ID: <L4tJmrRtSLxPxO4Ts-QHF8QuUdPedhLTl5Nx9AiwlXw=.04954bd9-4b33-488f-a6b4-df1c032bd423@github.com>

On Mon, 15 Apr 2024 13:41:29 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> doc/GUIDE.md line 869:
>> 
>>> 867:   WARNING: Skipping Foo (type Declared(Foo) is not supported)
>>> 868:   ```
>>> 869: 
>> 
>> Bitfields missing?
>> Also, support for primitive types > 64 bits.
>
> Bitfields is there. I'll add an item for types > 64 bits

I see bitfields now, but we should say something for e.g. `long double` on Linux

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

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

From jvernee at openjdk.org  Mon Apr 15 13:55:04 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 13:55:04 GMT
Subject: RFR: Add jextract guide [v6]
In-Reply-To: <m0Cey1wj33xqxWXBIzDS2KNtLXqVwhQjaajIlqGICGg=.28e15c7c-59db-4558-b73a-186858c08a18@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <bePF6GjJDM37WgE7nfq_8R1jxyJYXJmXwOjmKl46Vzc=.0ed30ccb-b91f-4684-8427-8ccaabd44bf4@github.com>
 <m0Cey1wj33xqxWXBIzDS2KNtLXqVwhQjaajIlqGICGg=.28e15c7c-59db-4558-b73a-186858c08a18@github.com>
Message-ID: <NfnQRfd9dlAgVlmYP1HHEpd-ECl-65yNZvx4lXwckls=.2e0b651d-6a49-4426-be36-9a2e7cb54614@github.com>

On Mon, 15 Apr 2024 13:41:51 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   review comments
>
> doc/GUIDE.md line 79:
> 
>> 77: [libclang](https://clang.llvm.org/docs/LibClang.html) native library in order to parse C sources).
>> 78: 
>> 79: ### Preprocessor Definitions
> 
> IMHO both this and the following section is not important enough to appear so early in the document. If we went straight to "Using The Code Generated By Jextract" we would not lose anything - then after that section, we can provide more details about various aspects/options.

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.

> doc/GUIDE.md line 848:
> 
>> 846: ## Unsupported Features
>> 847: 
>> 848: There are several elements for which jextract can not generate bindings:
> 
> element seems a bit vague, maybe "C program elements" could be better, although in this cases I suppose most developers will think about the term "features". Consider just having a bullet list and skip the first statement (after all, the title says it all). Note also the list is provided here:
> https://jdk.java.net/jextract/
> (maybe we should drop it from there in the future, to avoid duplication?)

Yeah, we probably just want to link to the guide from the download page

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

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

From jvernee at openjdk.org  Mon Apr 15 14:04:24 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 14:04:24 GMT
Subject: RFR: Add jextract guide [v8]
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <rXKGWPvUPAYziz8YHWL1ar85nsYCUeFfikajGMfPmW4=.492368ed-3c7a-469d-b90e-79af05e832a0@github.com>

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

Jorn Vernee has updated the pull request incrementally with two additional commits since the last revision:

 - try fix numbered list
 - more review comments + add para about default library loading

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/231/files
  - new: https://git.openjdk.org/jextract/pull/231/files/a9e7bb8b..af44d7fc

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=07
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=06-07

  Stats: 16 lines in 1 file changed: 9 ins; 1 del; 6 mod
  Patch: https://git.openjdk.org/jextract/pull/231.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/231/head:pull/231

PR: https://git.openjdk.org/jextract/pull/231

From mcimadamore at openjdk.org  Mon Apr 15 14:04:24 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Mon, 15 Apr 2024 14:04:24 GMT
Subject: RFR: Add jextract guide [v6]
In-Reply-To: <10I-po0ckrQYYl9M4VpnDgjDYFp6WEjU5AGvrAOxieQ=.81e6433f-caf8-4bb5-9fd6-57c54146f2bc@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <bePF6GjJDM37WgE7nfq_8R1jxyJYXJmXwOjmKl46Vzc=.0ed30ccb-b91f-4684-8427-8ccaabd44bf4@github.com>
 <m0Cey1wj33xqxWXBIzDS2KNtLXqVwhQjaajIlqGICGg=.28e15c7c-59db-4558-b73a-186858c08a18@github.com>
 <10I-po0ckrQYYl9M4VpnDgjDYFp6WEjU5AGvrAOxieQ=.81e6433f-caf8-4bb5-9fd6-57c54146f2bc@github.com>
Message-ID: <E-Gc6jvzpCgw7fZPHkOFRZjwRW0ulhG4FwcdIg3Dbnc=.cf7acd24-3432-4d85-b577-18feade7ed0f@github.com>

On Mon, 15 Apr 2024 13:37:01 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> doc/GUIDE.md line 147:
>> 
>>> 145: some examples of how to use the generated Java code.
>>> 146: 
>>> 147: Most of the methods that jextract generates are `static`, and are designed to be imported
>> 
>> Uhm - I think the paras you moved fitted nicely in this introductory section
>
> I think they could go in either section? But, this way, we can discuss the `--header-class-name` option in the section about running, which I think makes more sense.

On a second look, it makes sense in this updated version.

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

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

From jvernee at openjdk.org  Mon Apr 15 14:04:24 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 14:04:24 GMT
Subject: RFR: Add jextract guide [v6]
In-Reply-To: <W-Hr2KTkF7kSjx13sh78UHcAGUSsXyHAji2H7xtypa0=.3a89ef95-95b0-4f51-8dc2-709e3740fb41@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <bePF6GjJDM37WgE7nfq_8R1jxyJYXJmXwOjmKl46Vzc=.0ed30ccb-b91f-4684-8427-8ccaabd44bf4@github.com>
 <m0Cey1wj33xqxWXBIzDS2KNtLXqVwhQjaajIlqGICGg=.28e15c7c-59db-4558-b73a-186858c08a18@github.com>
 <10I-po0ckrQYYl9M4VpnDgjDYFp6WEjU5AGvrAOxieQ=.81e6433f-caf8-4bb5-9fd6-57c54146f2bc@github.com>
 <W-Hr2KTkF7kSjx13sh78UHcAGUSsXyHAji2H7xtypa0=.3a89ef95-95b0-4f51-8dc2-709e3740fb41@github.com>
Message-ID: <335T64le_vblLV1YHim9GGZpZOzusm9tshiXj2diDCs=.9859623b-4ff6-4b92-bc0c-4869ceab8523@github.com>

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

>> I don't think it's possible to start a markdown list at `2`, but I will try
>
> Looks like this doesn't work unfortunately.

No, wait, got it working after all.

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

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

From jvernee at openjdk.org  Mon Apr 15 14:04:24 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 14:04:24 GMT
Subject: RFR: Add jextract guide [v6]
In-Reply-To: <10I-po0ckrQYYl9M4VpnDgjDYFp6WEjU5AGvrAOxieQ=.81e6433f-caf8-4bb5-9fd6-57c54146f2bc@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <bePF6GjJDM37WgE7nfq_8R1jxyJYXJmXwOjmKl46Vzc=.0ed30ccb-b91f-4684-8427-8ccaabd44bf4@github.com>
 <m0Cey1wj33xqxWXBIzDS2KNtLXqVwhQjaajIlqGICGg=.28e15c7c-59db-4558-b73a-186858c08a18@github.com>
 <10I-po0ckrQYYl9M4VpnDgjDYFp6WEjU5AGvrAOxieQ=.81e6433f-caf8-4bb5-9fd6-57c54146f2bc@github.com>
Message-ID: <W-Hr2KTkF7kSjx13sh78UHcAGUSsXyHAji2H7xtypa0=.3a89ef95-95b0-4f51-8dc2-709e3740fb41@github.com>

On Mon, 15 Apr 2024 13:37:51 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> doc/GUIDE.md line 226:
>> 
>>> 224: First and foremost, there is a static wrapper method that is generated that can be used to
>>> 225: call the C function (1). Besides that, there are also several accessors that return
>>> 226: additional meta-data for the method: the function's address, represented as a
>> 
>> Should we use a numbered list here too?
>
> I don't think it's possible to start a markdown list at `2`, but I will try

Looks like this doesn't work unfortunately.

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

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

From mcimadamore at openjdk.org  Mon Apr 15 14:07:03 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Mon, 15 Apr 2024 14:07:03 GMT
Subject: RFR: Add jextract guide [v6]
In-Reply-To: <NfnQRfd9dlAgVlmYP1HHEpd-ECl-65yNZvx4lXwckls=.2e0b651d-6a49-4426-be36-9a2e7cb54614@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <bePF6GjJDM37WgE7nfq_8R1jxyJYXJmXwOjmKl46Vzc=.0ed30ccb-b91f-4684-8427-8ccaabd44bf4@github.com>
 <m0Cey1wj33xqxWXBIzDS2KNtLXqVwhQjaajIlqGICGg=.28e15c7c-59db-4558-b73a-186858c08a18@github.com>
 <NfnQRfd9dlAgVlmYP1HHEpd-ECl-65yNZvx4lXwckls=.2e0b651d-6a49-4426-be36-9a2e7cb54614@github.com>
Message-ID: <idtVFJetVklo5cUo87Ep3gplHw4fEwXjb0m3WGwLs7I=.d58b7f44-e8fb-4252-83d1-a71a00f3adde@github.com>

On Mon, 15 Apr 2024 13:52:07 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> doc/GUIDE.md line 79:
>> 
>>> 77: [libclang](https://clang.llvm.org/docs/LibClang.html) native library in order to parse C sources).
>>> 78: 
>>> 79: ### Preprocessor Definitions
>> 
>> IMHO both this and the following section is not important enough to appear so early in the document. If we went straight to "Using The Code Generated By Jextract" we would not lose anything - then after that section, we can provide more details about various aspects/options.
>
> 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.

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

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

From mcimadamore at openjdk.org  Mon Apr 15 14:10:02 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Mon, 15 Apr 2024 14:10:02 GMT
Subject: RFR: Add jextract guide [v8]
In-Reply-To: <rXKGWPvUPAYziz8YHWL1ar85nsYCUeFfikajGMfPmW4=.492368ed-3c7a-469d-b90e-79af05e832a0@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <rXKGWPvUPAYziz8YHWL1ar85nsYCUeFfikajGMfPmW4=.492368ed-3c7a-469d-b90e-79af05e832a0@github.com>
Message-ID: <ahhjXA6cfAPp88XaxMWXaRe7fAmyaRkSJapO4kM82Sk=.6d16c41c-25a6-44b1-a89d-9cb2a0314217@github.com>

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

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> Jorn Vernee has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - try fix numbered list
>  - more review comments + add para about default library loading

doc/GUIDE.md line 234:

> 232: call the C function (1). Besides that, there are also several accessors that return
> 233: additional meta-data for the method:
> 234: 

You could also add an item for (1) instead of having separate text above?

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

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

From jvernee at openjdk.org  Mon Apr 15 14:14:18 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 14:14:18 GMT
Subject: RFR: Add jextract guide [v9]
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <t1XNqWjDVvF9E574Glown79MD8g9mXrrvmwZiDJcnS4=.8ae0d9aa-ba0a-4519-a262-6f3d827d1903@github.com>

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:

  more list items

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/231/files
  - new: https://git.openjdk.org/jextract/pull/231/files/af44d7fc..a68da7b4

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=08
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=07-08

  Stats: 7 lines in 1 file changed: 4 ins; 0 del; 3 mod
  Patch: https://git.openjdk.org/jextract/pull/231.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/231/head:pull/231

PR: https://git.openjdk.org/jextract/pull/231

From jvernee at openjdk.org  Mon Apr 15 14:14:18 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 14:14:18 GMT
Subject: RFR: Add jextract guide [v8]
In-Reply-To: <ahhjXA6cfAPp88XaxMWXaRe7fAmyaRkSJapO4kM82Sk=.6d16c41c-25a6-44b1-a89d-9cb2a0314217@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <rXKGWPvUPAYziz8YHWL1ar85nsYCUeFfikajGMfPmW4=.492368ed-3c7a-469d-b90e-79af05e832a0@github.com>
 <ahhjXA6cfAPp88XaxMWXaRe7fAmyaRkSJapO4kM82Sk=.6d16c41c-25a6-44b1-a89d-9cb2a0314217@github.com>
Message-ID: <1HOxmyQwMY8H9GCN-zaWY3kmwXNdc_Iu4GPN5io6CFY=.f4a55d56-603f-4fa9-aca9-c6b52d7621e5@github.com>

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

>> Jorn Vernee has updated the pull request incrementally with two additional commits since the last revision:
>> 
>>  - try fix numbered list
>>  - more review comments + add para about default library loading
>
> doc/GUIDE.md line 234:
> 
>> 232: call the C function (1). Besides that, there are also several accessors that return
>> 233: additional meta-data for the method:
>> 234: 
> 
> You could also add an item for (1) instead of having separate text above?

Done

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

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

From mcimadamore at openjdk.org  Mon Apr 15 14:14:18 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Mon, 15 Apr 2024 14:14:18 GMT
Subject: RFR: Add jextract guide [v6]
In-Reply-To: <10I-po0ckrQYYl9M4VpnDgjDYFp6WEjU5AGvrAOxieQ=.81e6433f-caf8-4bb5-9fd6-57c54146f2bc@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <bePF6GjJDM37WgE7nfq_8R1jxyJYXJmXwOjmKl46Vzc=.0ed30ccb-b91f-4684-8427-8ccaabd44bf4@github.com>
 <m0Cey1wj33xqxWXBIzDS2KNtLXqVwhQjaajIlqGICGg=.28e15c7c-59db-4558-b73a-186858c08a18@github.com>
 <10I-po0ckrQYYl9M4VpnDgjDYFp6WEjU5AGvrAOxieQ=.81e6433f-caf8-4bb5-9fd6-57c54146f2bc@github.com>
Message-ID: <OHqZ4PAPp8r319omclgKQcY09FJuE4RjIo45i3KstVg=.a256a1cc-3c9c-406f-a672-bcad1b935f1b@github.com>

On Mon, 15 Apr 2024 13:39:03 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> doc/GUIDE.md line 306:
>> 
>>> 304: 
>>> 305: Note that for macros, jextract only generates an accessor when it sees a macro definition,
>>> 306: like the one in the example, in the header files it parses. When a macro is only defined
>> 
>> Suggestion:
>> 
>> like the one in the example, in the header files it parses. When a macro is defined
>
> `only` is relevant here. If a macro is defined using `#define` _and_ on the command line, jextract will generate an accessor.

I understand what you wanted to stress - but IMHO `only` is still redundant. E.g. "when a macro is defined using -D" is still plenty clear? Using `only` seems to convey some kind of deeper distinction e.g. that macros with -D are somehow "less macros" than the other ones. At least it's how it reads to me.

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

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

From mcimadamore at openjdk.org  Mon Apr 15 14:16:56 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Mon, 15 Apr 2024 14:16:56 GMT
Subject: RFR: Add jextract guide [v8]
In-Reply-To: <1HOxmyQwMY8H9GCN-zaWY3kmwXNdc_Iu4GPN5io6CFY=.f4a55d56-603f-4fa9-aca9-c6b52d7621e5@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <rXKGWPvUPAYziz8YHWL1ar85nsYCUeFfikajGMfPmW4=.492368ed-3c7a-469d-b90e-79af05e832a0@github.com>
 <ahhjXA6cfAPp88XaxMWXaRe7fAmyaRkSJapO4kM82Sk=.6d16c41c-25a6-44b1-a89d-9cb2a0314217@github.com>
 <1HOxmyQwMY8H9GCN-zaWY3kmwXNdc_Iu4GPN5io6CFY=.f4a55d56-603f-4fa9-aca9-c6b52d7621e5@github.com>
Message-ID: <62OVQDH0nC6icQsBctGQ_XHxkgKxAJq6VU7G--DQhvM=.0592efeb-52ca-4219-88a4-3078d0e51b41@github.com>

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

>> doc/GUIDE.md line 234:
>> 
>>> 232: call the C function (1). Besides that, there are also several accessors that return
>>> 233: additional meta-data for the method:
>>> 234: 
>> 
>> You could also add an item for (1) instead of having separate text above?
>
> Done

Now veering into nitpicks: but I note that we have an asymmetry between structs and functions. In functions we try to call out the function accessor (probably on the basis that this is the symbol the user is likely to be looking for). But for structs we just list all the members one after the other (even though the most likely is probably (1) - e.g. getter/setter). I think the document could be improved (optionally) by rectifying this one way or the other.

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

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

From jvernee at openjdk.org  Mon Apr 15 14:59:07 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 14:59:07 GMT
Subject: RFR: Add jextract guide [v6]
In-Reply-To: <idtVFJetVklo5cUo87Ep3gplHw4fEwXjb0m3WGwLs7I=.d58b7f44-e8fb-4252-83d1-a71a00f3adde@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <bePF6GjJDM37WgE7nfq_8R1jxyJYXJmXwOjmKl46Vzc=.0ed30ccb-b91f-4684-8427-8ccaabd44bf4@github.com>
 <m0Cey1wj33xqxWXBIzDS2KNtLXqVwhQjaajIlqGICGg=.28e15c7c-59db-4558-b73a-186858c08a18@github.com>
 <NfnQRfd9dlAgVlmYP1HHEpd-ECl-65yNZvx4lXwckls=.2e0b651d-6a49-4426-be36-9a2e7cb54614@github.com>
 <idtVFJetVklo5cUo87Ep3gplHw4fEwXjb0m3WGwLs7I=.d58b7f44-e8fb-4252-83d1-a71a00f3adde@github.com>
Message-ID: <tamVnuRhO9HPb4yL-7-AEObu4-qJrwWjkuis3EXyIqI=.720318fd-1d6b-4e8c-ae6c-ea375cb3a4a6@github.com>

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

From mcimadamore at openjdk.org  Mon Apr 15 15:09:03 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Mon, 15 Apr 2024 15:09:03 GMT
Subject: RFR: Add jextract guide [v6]
In-Reply-To: <tamVnuRhO9HPb4yL-7-AEObu4-qJrwWjkuis3EXyIqI=.720318fd-1d6b-4e8c-ae6c-ea375cb3a4a6@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <bePF6GjJDM37WgE7nfq_8R1jxyJYXJmXwOjmKl46Vzc=.0ed30ccb-b91f-4684-8427-8ccaabd44bf4@github.com>
 <m0Cey1wj33xqxWXBIzDS2KNtLXqVwhQjaajIlqGICGg=.28e15c7c-59db-4558-b73a-186858c08a18@github.com>
 <NfnQRfd9dlAgVlmYP1HHEpd-ECl-65yNZvx4lXwckls=.2e0b651d-6a49-4426-be36-9a2e7cb54614@github.com>
 <idtVFJetVklo5cUo87Ep3gplHw4fEwXjb0m3WGwLs7I=.d58b7f44-e8fb-4252-83d1-a71a00f3adde@github.com>
 <tamVnuRhO9HPb4yL-7-AEObu4-qJrwWjkuis3EXyIqI=.720318fd-1d6b-4e8c-ae6c-ea375cb3a4a6@github.com>
Message-ID: <s5O7HyaIYMEs1yqD3aXEiYaLGVc6JRZPDBq-Of7ZKbA=.bf58cacf-667d-40ba-bf41-74f1c4d12659@github.com>

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

From jvernee at openjdk.org  Mon Apr 15 15:30:13 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 15:30:13 GMT
Subject: RFR: Add jextract guide [v10]
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <rOivIVwjwYWDeytVdA3EIM1ojA7Ao1uJW_91kA_sTCo=.02e91482-5cfc-4dfb-93d3-fe6451e56ef5@github.com>

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:

  move defines & library loading sections out-of-line

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/231/files
  - new: https://git.openjdk.org/jextract/pull/231/files/a68da7b4..fd4d067c

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=09
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=08-09

  Stats: 159 lines in 1 file changed: 84 ins; 69 del; 6 mod
  Patch: https://git.openjdk.org/jextract/pull/231.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/231/head:pull/231

PR: https://git.openjdk.org/jextract/pull/231

From jvernee at openjdk.org  Mon Apr 15 15:30:13 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 15:30:13 GMT
Subject: RFR: Add jextract guide [v6]
In-Reply-To: <s5O7HyaIYMEs1yqD3aXEiYaLGVc6JRZPDBq-Of7ZKbA=.bf58cacf-667d-40ba-bf41-74f1c4d12659@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <bePF6GjJDM37WgE7nfq_8R1jxyJYXJmXwOjmKl46Vzc=.0ed30ccb-b91f-4684-8427-8ccaabd44bf4@github.com>
 <m0Cey1wj33xqxWXBIzDS2KNtLXqVwhQjaajIlqGICGg=.28e15c7c-59db-4558-b73a-186858c08a18@github.com>
 <NfnQRfd9dlAgVlmYP1HHEpd-ECl-65yNZvx4lXwckls=.2e0b651d-6a49-4426-be36-9a2e7cb54614@github.com>
 <idtVFJetVklo5cUo87Ep3gplHw4fEwXjb0m3WGwLs7I=.d58b7f44-e8fb-4252-83d1-a71a00f3adde@github.com>
 <tamVnuRhO9HPb4yL-7-AEObu4-qJrwWjkuis3EXyIqI=.720318fd-1d6b-4e8c-ae6c-ea375cb3a4a6@github.com>
 <s5O7HyaIYMEs1yqD3aXEiYaLGVc6JRZPDBq-Of7ZKbA=.bf58cacf-667d-40ba-bf41-74f1c4d12659@github.com>
Message-ID: <GcwiUg4CGULA-6Tn_19BIBVHRMNCiFJEEX60xek5zNE=.5d4494c1-501e-40f7-a316-d8ede3829d12@github.com>

On Mon, 15 Apr 2024 15:05:22 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> 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.

I gave this a try in the latest version. Still not sure which one is better, but I don't mind either way. I put all the sections after the examples in an 'Advanced' section as well.

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

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

From mcimadamore at openjdk.org  Mon Apr 15 15:41:05 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Mon, 15 Apr 2024 15:41:05 GMT
Subject: RFR: Add jextract guide [v6]
In-Reply-To: <GcwiUg4CGULA-6Tn_19BIBVHRMNCiFJEEX60xek5zNE=.5d4494c1-501e-40f7-a316-d8ede3829d12@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <bePF6GjJDM37WgE7nfq_8R1jxyJYXJmXwOjmKl46Vzc=.0ed30ccb-b91f-4684-8427-8ccaabd44bf4@github.com>
 <m0Cey1wj33xqxWXBIzDS2KNtLXqVwhQjaajIlqGICGg=.28e15c7c-59db-4558-b73a-186858c08a18@github.com>
 <NfnQRfd9dlAgVlmYP1HHEpd-ECl-65yNZvx4lXwckls=.2e0b651d-6a49-4426-be36-9a2e7cb54614@github.com>
 <idtVFJetVklo5cUo87Ep3gplHw4fEwXjb0m3WGwLs7I=.d58b7f44-e8fb-4252-83d1-a71a00f3adde@github.com>
 <tamVnuRhO9HPb4yL-7-AEObu4-qJrwWjkuis3EXyIqI=.720318fd-1d6b-4e8c-ae6c-ea375cb3a4a6@github.com>
 <s5O7HyaIYMEs1yqD3aXEiYaLGVc6JRZPDBq-Of7ZKbA=.bf58cacf-667d-40ba-bf41-74f1c4d12659@github.com>
 <GcwiUg4CGULA-6Tn_19BIBVHRMNCiFJEEX60xek5zNE=.5d4494c1-501e-40f7-a316-d8ede3829d12@github.com>
Message-ID: <4WmMyM4njadqmY88C1YfgbIEo_oPU5nF8b92jmkxOeg=.dd15cb44-043a-4f96-836c-0d8f5d76128d@github.com>

On Mon, 15 Apr 2024 15:26:59 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> 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.
>
> I gave this a try in the latest version. Still not sure which one is better, but I don't mind either way. I put all the sections after the examples in an 'Advanced' section as well.

I personally like the new changes a lot! I find the "running jextract" section very informative, providing all the major info w/o overstaying its welcome. Also it points to several other sections in the doc, so it acts a bit as a mental map, which is good.

I have some reservation about "unsupported features" being down in "Advanced" - should that be the last section in "Using jextract bindings" instead? (e.g. first we show what works, and then if the reader was expecting something else, we have a section for that too). Or, maybe pull it more "up front". Right now it seems kind of buried in other stuff, even thought it seems generally useful.

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

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

From jvernee at openjdk.org  Mon Apr 15 15:58:16 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 15:58:16 GMT
Subject: RFR: Add jextract guide [v6]
In-Reply-To: <4WmMyM4njadqmY88C1YfgbIEo_oPU5nF8b92jmkxOeg=.dd15cb44-043a-4f96-836c-0d8f5d76128d@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <bePF6GjJDM37WgE7nfq_8R1jxyJYXJmXwOjmKl46Vzc=.0ed30ccb-b91f-4684-8427-8ccaabd44bf4@github.com>
 <m0Cey1wj33xqxWXBIzDS2KNtLXqVwhQjaajIlqGICGg=.28e15c7c-59db-4558-b73a-186858c08a18@github.com>
 <NfnQRfd9dlAgVlmYP1HHEpd-ECl-65yNZvx4lXwckls=.2e0b651d-6a49-4426-be36-9a2e7cb54614@github.com>
 <idtVFJetVklo5cUo87Ep3gplHw4fEwXjb0m3WGwLs7I=.d58b7f44-e8fb-4252-83d1-a71a00f3adde@github.com>
 <tamVnuRhO9HPb4yL-7-AEObu4-qJrwWjkuis3EXyIqI=.720318fd-1d6b-4e8c-ae6c-ea375cb3a4a6@github.com>
 <s5O7HyaIYMEs1yqD3aXEiYaLGVc6JRZPDBq-Of7ZKbA=.bf58cacf-667d-40ba-bf41-74f1c4d12659@github.com>
 <GcwiUg4CGULA-6Tn_19BIBVHRMNCiFJEEX60xek5zNE=.5d4494c1-501e-40f7-a316-d8ede3829d12@github.com>
 <4WmMyM4njadqmY88C1YfgbIEo_oPU5nF8b92jmkxOeg=.dd15cb44-043a-4f96-836c-0d8f5d76128d@github.com>
Message-ID: <yPI-OWEj94uwPghbpprHQUtrZ_XFKC-5k5VlcJN6nss=.69dc1ef3-dc9f-4237-9a57-1b163f6a0bed@github.com>

On Mon, 15 Apr 2024 15:37:57 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> I gave this a try in the latest version. Still not sure which one is better, but I don't mind either way. I put all the sections after the examples in an 'Advanced' section as well.
>
> I personally like the new changes a lot! I find the "running jextract" section very informative, providing all the major info w/o overstaying its welcome. Also it points to several other sections in the doc, so it acts a bit as a mental map, which is good.
> 
> I have some reservation about "unsupported features" being down in "Advanced" - should that be the last section in "Using jextract bindings" instead? (e.g. first we show what works, and then if the reader was expecting something else, we have a section for that too). Or, maybe pull it more "up front". Right now it seems kind of buried in other stuff, even thought it seems generally useful.

Ok, I'll keep it like this then.

I'll move the unsupported feature to the end of the 'using' section.

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

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

From jvernee at openjdk.org  Mon Apr 15 15:58:16 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 15:58:16 GMT
Subject: RFR: Add jextract guide [v11]
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <4r2YS15o1QGHAUfhao0UiZ4JTALOhCF0ZzXJz5pg5-c=.ae59b3c5-1a31-43fa-bd94-c949a056dbec@github.com>

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:

  move unsupported features to end of using section

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/231/files
  - new: https://git.openjdk.org/jextract/pull/231/files/fd4d067c..4491aa6f

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=10
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=09-10

  Stats: 48 lines in 1 file changed: 25 ins; 23 del; 0 mod
  Patch: https://git.openjdk.org/jextract/pull/231.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/231/head:pull/231

PR: https://git.openjdk.org/jextract/pull/231

From jvernee at openjdk.org  Mon Apr 15 23:01:12 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 23:01:12 GMT
Subject: RFR: Add jextract guide [v12]
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <iEJjiahjmE8sOYdMQom5y8ZjW_OeNR1Fcd-xjeU2hzo=.9571a32b-b921-4c4f-b1c6-41cb530d61cc@github.com>

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:

  Update doc/GUIDE.md
  
  Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/231/files
  - new: https://git.openjdk.org/jextract/pull/231/files/4491aa6f..5de1f4fd

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=11
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=10-11

  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jextract/pull/231.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/231/head:pull/231

PR: https://git.openjdk.org/jextract/pull/231

From jvernee at openjdk.org  Mon Apr 15 23:01:12 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 23:01:12 GMT
Subject: RFR: Add jextract guide [v11]
In-Reply-To: <4r2YS15o1QGHAUfhao0UiZ4JTALOhCF0ZzXJz5pg5-c=.ae59b3c5-1a31-43fa-bd94-c949a056dbec@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <4r2YS15o1QGHAUfhao0UiZ4JTALOhCF0ZzXJz5pg5-c=.ae59b3c5-1a31-43fa-bd94-c949a056dbec@github.com>
Message-ID: <f61Lc-mpBSOhvZX-ym37r8zLWb7CCjxzBy8C0uYURAo=.3aff7ef1-f3fc-4695-a906-79c6e3dae61e@github.com>

On Mon, 15 Apr 2024 15:58:16 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
> 
>   move unsupported features to end of using section

I think I've addressed all review comments. Please have another look

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

PR Comment: https://git.openjdk.org/jextract/pull/231#issuecomment-2057947555

From jvernee at openjdk.org  Mon Apr 15 23:01:12 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Mon, 15 Apr 2024 23:01:12 GMT
Subject: RFR: Add jextract guide [v6]
In-Reply-To: <OHqZ4PAPp8r319omclgKQcY09FJuE4RjIo45i3KstVg=.a256a1cc-3c9c-406f-a672-bcad1b935f1b@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <bePF6GjJDM37WgE7nfq_8R1jxyJYXJmXwOjmKl46Vzc=.0ed30ccb-b91f-4684-8427-8ccaabd44bf4@github.com>
 <m0Cey1wj33xqxWXBIzDS2KNtLXqVwhQjaajIlqGICGg=.28e15c7c-59db-4558-b73a-186858c08a18@github.com>
 <10I-po0ckrQYYl9M4VpnDgjDYFp6WEjU5AGvrAOxieQ=.81e6433f-caf8-4bb5-9fd6-57c54146f2bc@github.com>
 <OHqZ4PAPp8r319omclgKQcY09FJuE4RjIo45i3KstVg=.a256a1cc-3c9c-406f-a672-bcad1b935f1b@github.com>
Message-ID: <FHeKJsaVKDn8iNBicN2yy1CR94pMvu7u2kPTTMURldg=.6837393a-e4f5-4f6f-8d98-63519be456b0@github.com>

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

>> `only` is relevant here. If a macro is defined using `#define` _and_ on the command line, jextract will generate an accessor.
>
> I understand what you wanted to stress - but IMHO `only` is still redundant. E.g. "when a macro is defined using -D" is still plenty clear? Using `only` seems to convey some kind of deeper distinction e.g. that macros with -D are somehow "less macros" than the other ones. At least it's how it reads to me.

Ok, removed.

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

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

From nlisker at openjdk.org  Tue Apr 16 00:14:02 2024
From: nlisker at openjdk.org (Nir Lisker)
Date: Tue, 16 Apr 2024 00:14:02 GMT
Subject: RFR: Add jextract guide [v12]
In-Reply-To: <iEJjiahjmE8sOYdMQom5y8ZjW_OeNR1Fcd-xjeU2hzo=.9571a32b-b921-4c4f-b1c6-41cb530d61cc@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <iEJjiahjmE8sOYdMQom5y8ZjW_OeNR1Fcd-xjeU2hzo=.9571a32b-b921-4c4f-b1c6-41cb530d61cc@github.com>
Message-ID: <ENysF3gvErfbnQYZ-Auc-kx0zQt3vrG8AAsK8kftK28=.bffe737c-2562-4caa-b81d-cdd3bc8a913b@github.com>

On Mon, 15 Apr 2024 23:01:12 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Update doc/GUIDE.md
>   
>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>

Looks very good. Left some minor comments. Can be integrated after they are resolved.

README.md line 5:

> 3: `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/)).
> 4: 
> 5: :bulb: For instruction on how to use the jextract tool, please refer to the guide [here](doc/GUIDE.md)

Period at the end.

doc/GUIDE.md line 55:

> 53:   through `--output`)
> 54: - `--library mylib` tells jextract that the generated bindings should load the library
> 55:   called `mylib`. (The section on [library loading](#library-loading) discusses how is done)

"how is done" -> "how it's done."

doc/GUIDE.md line 59:

> 57: Note that specifying the wrong header file to jextract may result in errors during parsing.
> 58: Please consult the documentation of the library in question about which header file
> 59: should be included. This is also the header files that should be passed to jextract. If

These sentences mix plural and singular header file(s).

doc/GUIDE.md line 266:

> 264: using `-D` on the command line, no accessor will be generated.
> 265: 
> 266: ### Structs & Unions

This section follows an example using a struct. If there's no difference whatsoever compared to a union, this is fine. Otherwise, I will mention in the example where things might differ.

doc/GUIDE.md line 312:

> 310: ? ? public static MemorySegment reinterpret(MemorySegment addr, long elementCount,
> 311:             Arena arena, Consumer<MemorySegment> cleanup) { ... } // 6
> 312: }

I noticed that some of these methods are `final` and some aren't. Is this on purpose in jextract (why?), or just here?

doc/GUIDE.md line 739:

> 737: name is then mapped to a platform dependent name using [`System::mapLibraryName`](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/System.html#mapLibraryName(java.lang.String)).
> 738: This means, for instance, that on Linux, when specifying `--library mylib`, the bindings will
> 739: try to load `libmylib.so` using the OS-specific library loading mechanism on Linux, which

`libmylib.so` -> not `mylib.so`?

doc/GUIDE.md line 896:

> 894: 
> 895: Jextract uses an embedded clang compiler (through libclang) to parse header files. Users
> 896: can also specify additional clang compiler options, by creating a file named

"options," -> "options"

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

PR Review: https://git.openjdk.org/jextract/pull/231#pullrequestreview-2002311013
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566522599
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566523022
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566525138
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566544393
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566542910
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566560650
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566562931

From nlisker at openjdk.org  Tue Apr 16 00:14:02 2024
From: nlisker at openjdk.org (Nir Lisker)
Date: Tue, 16 Apr 2024 00:14:02 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <XbM1rOz1D1M3ckA__FjaNT3-DxBK-F1yKdY1KDI4Xzs=.becfe980-60ea-48a8-b9e9-a04aff4cce6a@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
 <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
 <IHF_qgv7NqL0pQK7Q5NKe40yAkNp7xGKf6gG7vJLO7I=.6658ec0c-1889-4539-933d-6a1422b7aa32@github.com>
 <HHSyqylnbUZ1ecEQC7GN4Go7qdFrg0x_UoMp184FBx8=.7eeccf7e-8642-4827-819b-8b377e6ad745@github.com>
 <7xCiGlW5c7wExsaeQ_ib9AzP3JHQ8Pleu897BqNyJfQ=.a2cc00af-bd59-466b-b565-20c98532e0a5@github.com>
 <XbM1rOz1D1M3ckA__FjaNT3-DxBK-F1yKdY1KDI4Xzs=.becfe980-60ea-48a8-b9e9-a04aff4cce6a@github.com>
Message-ID: <HFSyOUgwx3ynZb3blHMt_xO7SwYzCtYDqm8TOxolues=.fd2a957b-0489-47ab-b1f3-8b8bb4a4e7cc@github.com>

On Mon, 15 Apr 2024 13:39:47 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> Sorry, the example assumes that that the `call_me_back` function is also defined in the header file that jextract extracted, so a Java method would be generated for it.
>
> I would mentioned that. After all, this tool is meant to save Java developers from knowing the intricacies of the native language.

Was this resolved? I don't see a clarification (maybe I'm missing it).

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

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

From jvernee at openjdk.org  Tue Apr 16 01:16:01 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 16 Apr 2024 01:16:01 GMT
Subject: RFR: Add jextract guide [v12]
In-Reply-To: <ENysF3gvErfbnQYZ-Auc-kx0zQt3vrG8AAsK8kftK28=.bffe737c-2562-4caa-b81d-cdd3bc8a913b@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <iEJjiahjmE8sOYdMQom5y8ZjW_OeNR1Fcd-xjeU2hzo=.9571a32b-b921-4c4f-b1c6-41cb530d61cc@github.com>
 <ENysF3gvErfbnQYZ-Auc-kx0zQt3vrG8AAsK8kftK28=.bffe737c-2562-4caa-b81d-cdd3bc8a913b@github.com>
Message-ID: <Cc1M6qJiuKJPtInKivjyJXAywAfF3ljdcl61gx0E1Ko=.b537723a-c3d1-42da-83da-f0e893238621@github.com>

On Mon, 15 Apr 2024 23:36:30 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Update doc/GUIDE.md
>>   
>>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>
> doc/GUIDE.md line 266:
> 
>> 264: using `-D` on the command line, no accessor will be generated.
>> 265: 
>> 266: ### Structs & Unions
> 
> This section follows an example using a struct. If there's no difference whatsoever compared to a union, this is fine. Otherwise, I will mention in the example where things might differ.

It's exactly the same for both (I'll mention that as well)

> doc/GUIDE.md line 312:
> 
>> 310: ? ? public static MemorySegment reinterpret(MemorySegment addr, long elementCount,
>> 311:             Arena arena, Consumer<MemorySegment> cleanup) { ... } // 6
>> 312: }
> 
> I noticed that some of these methods are `final` and some aren't. Is this on purpose in jextract (why?), or just here?

static methods don't need to be `final`. I think that may be an artifact of some code sharing we do internally.

> doc/GUIDE.md line 739:
> 
>> 737: name is then mapped to a platform dependent name using [`System::mapLibraryName`](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/System.html#mapLibraryName(java.lang.String)).
>> 738: This means, for instance, that on Linux, when specifying `--library mylib`, the bindings will
>> 739: try to load `libmylib.so` using the OS-specific library loading mechanism on Linux, which
> 
> `libmylib.so` -> not `mylib.so`?

No, `mapLibraryName` adds the `lib` prefix on Linux

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566593004
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566592704
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566593792

From jvernee at openjdk.org  Tue Apr 16 01:23:01 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 16 Apr 2024 01:23:01 GMT
Subject: RFR: Add jextract guide [v12]
In-Reply-To: <ENysF3gvErfbnQYZ-Auc-kx0zQt3vrG8AAsK8kftK28=.bffe737c-2562-4caa-b81d-cdd3bc8a913b@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <iEJjiahjmE8sOYdMQom5y8ZjW_OeNR1Fcd-xjeU2hzo=.9571a32b-b921-4c4f-b1c6-41cb530d61cc@github.com>
 <ENysF3gvErfbnQYZ-Auc-kx0zQt3vrG8AAsK8kftK28=.bffe737c-2562-4caa-b81d-cdd3bc8a913b@github.com>
Message-ID: <vnqODK5sll28kCcRMU1obr8WDeQqxm4zI99EUkESbGU=.30f681c1-1236-4159-b042-0bf2516dfeee@github.com>

On Mon, 15 Apr 2024 23:01:03 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Update doc/GUIDE.md
>>   
>>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>
> doc/GUIDE.md line 55:
> 
>> 53:   through `--output`)
>> 54: - `--library mylib` tells jextract that the generated bindings should load the library
>> 55:   called `mylib`. (The section on [library loading](#library-loading) discusses how is done)
> 
> "how is done" -> "how it's done."

This should be have "this is"

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

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

From jvernee at openjdk.org  Tue Apr 16 01:23:01 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 16 Apr 2024 01:23:01 GMT
Subject: RFR: Add jextract guide [v5]
In-Reply-To: <HFSyOUgwx3ynZb3blHMt_xO7SwYzCtYDqm8TOxolues=.fd2a957b-0489-47ab-b1f3-8b8bb4a4e7cc@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <4AzowTCAzXXieA40qLGHTXZ0fEFRUi_kk_gW2ta9nJ4=.605bd63a-d4a8-421d-9043-39fa7d246299@github.com>
 <E5CutD2mITc6TkTyXYigKsCSOm9rfXD5pOG4H5wfUMw=.927be8ff-0d67-4545-b81b-4e0d27638e33@github.com>
 <IHF_qgv7NqL0pQK7Q5NKe40yAkNp7xGKf6gG7vJLO7I=.6658ec0c-1889-4539-933d-6a1422b7aa32@github.com>
 <HHSyqylnbUZ1ecEQC7GN4Go7qdFrg0x_UoMp184FBx8=.7eeccf7e-8642-4827-819b-8b377e6ad745@github.com>
 <7xCiGlW5c7wExsaeQ_ib9AzP3JHQ8Pleu897BqNyJfQ=.a2cc00af-bd59-466b-b565-20c98532e0a5@github.com>
 <XbM1rOz1D1M3ckA__FjaNT3-DxBK-F1yKdY1KDI4Xzs=.becfe980-60ea-48a8-b9e9-a04aff4cce6a@github.com>
 <HFSyOUgwx3ynZb3blHMt_xO7SwYzCtYDqm8TOxolues=.fd2a957b-0489-47ab-b1f3-8b8bb4a4e7cc@github.com>
Message-ID: <CSYI1MzcQQzYKY_uJ_WtNpGmDyZi7SSN7gsZ95efalU=.9c5687d6-8406-4b7b-a165-74d9022b192a@github.com>

On Mon, 15 Apr 2024 23:51:35 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> I would mentioned that. After all, this tool is meant to save Java developers from knowing the intricacies of the native language.
>
> Was this resolved? I don't see a clarification (maybe I'm missing it).

I put this:


We can call this function from Java as follows (assuming this function is also exported
through the header files passed to jextract)

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

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

From mcimadamore at openjdk.org  Tue Apr 16 08:31:02 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Tue, 16 Apr 2024 08:31:02 GMT
Subject: RFR: Add jextract guide [v12]
In-Reply-To: <iEJjiahjmE8sOYdMQom5y8ZjW_OeNR1Fcd-xjeU2hzo=.9571a32b-b921-4c4f-b1c6-41cb530d61cc@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <iEJjiahjmE8sOYdMQom5y8ZjW_OeNR1Fcd-xjeU2hzo=.9571a32b-b921-4c4f-b1c6-41cb530d61cc@github.com>
Message-ID: <OTgWvQFxjh7xQDmljyR5KmpZX6LyV2c25dIjkIoO3-M=.6b645e42-ee76-46ed-829c-adfcfa9e3ce5@github.com>

On Mon, 15 Apr 2024 23:01:12 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Update doc/GUIDE.md
>   
>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>

doc/GUIDE.md line 10:

> 8: by loading a native library (e.g., a `.so`/`.dll`/`.dylib` file), which is essentially an
> 9: archive of native functions and global variables. The user then has to look up the functions
> 10: they want to call using a `SymbolLookup`, and finally _link_ the functions by using the

There's some classes and methods referenced here - should we use links? (don't have strong opinion)

doc/GUIDE.md line 20:

> 18: The samples under the [`samples`](samples) direcotry are also a good source of examples.
> 19: 
> 20: Note that at this time, jextract only supports C header files. If you have a library written

should we say "jextract (and FFM) only support..." ?

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

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

From mcimadamore at openjdk.org  Tue Apr 16 08:41:01 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Tue, 16 Apr 2024 08:41:01 GMT
Subject: RFR: Add jextract guide [v12]
In-Reply-To: <iEJjiahjmE8sOYdMQom5y8ZjW_OeNR1Fcd-xjeU2hzo=.9571a32b-b921-4c4f-b1c6-41cb530d61cc@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <iEJjiahjmE8sOYdMQom5y8ZjW_OeNR1Fcd-xjeU2hzo=.9571a32b-b921-4c4f-b1c6-41cb530d61cc@github.com>
Message-ID: <CyGBoZyHZVFJTTdC7eZEp46z71vYl1fgCmwko4Xlp74=.929b3066-eff7-436d-9c6d-5d211cc99a52@github.com>

On Mon, 15 Apr 2024 23:01:12 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Update doc/GUIDE.md
>   
>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>

doc/GUIDE.md line 70:

> 68: [library loading](#library-loading) for more information.
> 69: 
> 70: Besides these options, it is also possible to filter the output of jextract using one of the `--include-XXX` options

Suggestion:

Besides these options, it is also possible to filter the output of jextract using one of the `--include-XYZ` options

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

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

From mcimadamore at openjdk.org  Tue Apr 16 08:53:03 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Tue, 16 Apr 2024 08:53:03 GMT
Subject: RFR: Add jextract guide [v12]
In-Reply-To: <iEJjiahjmE8sOYdMQom5y8ZjW_OeNR1Fcd-xjeU2hzo=.9571a32b-b921-4c4f-b1c6-41cb530d61cc@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <iEJjiahjmE8sOYdMQom5y8ZjW_OeNR1Fcd-xjeU2hzo=.9571a32b-b921-4c4f-b1c6-41cb530d61cc@github.com>
Message-ID: <sK69tgTQuczfpl48oVlorpd-TICIRpJBFEclU1Gi52M=.0cf8206e-757e-4dce-93e7-7bccdc6f2caa@github.com>

On Mon, 15 Apr 2024 23:01:12 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Update doc/GUIDE.md
>   
>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>

doc/GUIDE.md line 236:

> 234: ```
> 235: 
> 236: Jextract will generate a set of simple getter methods to access the constant values of the

Nit: maybe omit the word `set` - e.g. just "generate simple getter methods...". Seeing "set" so close to "getter" might be confusing.

doc/GUIDE.md line 262:

> 260: through the FFM API.
> 261: 
> 262: Note that for macros, jextract only generates an accessor when it sees a macro definition,

Feels like here we need a link to the preprocessor section

doc/GUIDE.md line 376:

> 374: ```
> 375: 
> 376: The pointer that is returned by the corresponding method that jextract generates

Consider streamlining this by saying "The pointer that is returned by new_point does not have..."

doc/GUIDE.md line 378:

> 376: The pointer that is returned by the corresponding method that jextract generates
> 377: for this function does not have the correct bounds or lifetime associated with it.
> 378: These things are not possible to figure out automatically (for instance, a pointer

Suggestion:

These properties cannot be inferred: for instance, a pointer...

doc/GUIDE.md line 426:

> 424: ```
> 425: 
> 426: We again have a meta-data accessor for the function descriptor (`descriptor()`). There's

Maybe here using numbers in the code and a numbered list would be (a) more consistent and (b) more readable

doc/GUIDE.md line 682:

> 680: 
> 681: - Certain C types bigger than 64 bits (e.g. `long double` on Linux).
> 682: - Function-like macros (as mentioned in the [section on constants](#constants-macros--enums))

I wonder if here we got the reference backwards - e.g. perhaps the section on constants should just say that function-like macros are not supported and point here, then here we could say what workarounds could be used in more details?

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

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566978455
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566983513
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566987029
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566987831
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566990577
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566981579

From mcimadamore at openjdk.org  Tue Apr 16 09:03:05 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Tue, 16 Apr 2024 09:03:05 GMT
Subject: RFR: Add jextract guide [v12]
In-Reply-To: <iEJjiahjmE8sOYdMQom5y8ZjW_OeNR1Fcd-xjeU2hzo=.9571a32b-b921-4c4f-b1c6-41cb530d61cc@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <iEJjiahjmE8sOYdMQom5y8ZjW_OeNR1Fcd-xjeU2hzo=.9571a32b-b921-4c4f-b1c6-41cb530d61cc@github.com>
Message-ID: <UKHFHM2kPX9Bv2xkau1xqYCJU3MIeqNy8AEv_k5pJGE=.b3db5e44-cea7-4c58-a7e6-a377f1b12ae2@github.com>

On Mon, 15 Apr 2024 23:01:12 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Update doc/GUIDE.md
>   
>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>

I've reviewed the document again. It looks very good, and the structure of the documents strikes me as just right (well done!). I've left picky comments (e.g. 99% review), which I consider optional. I'm ok with the PR being pushed in its current form.

doc/GUIDE.md line 676:

> 674: In the above snippet, note that the load of the `baz` field value on the last line will
> 675: _see_ the update to the `bar` field of the `foo` instance on the line before.
> 676: 

Perhaps we could also add a section (maybe in a followup PR) on fields/globals with array types, as jextract generates extra metadata (e.g. dimensions) and the Java type used for these accesses is MemorySegment (with bulk copy support on `set`)

doc/GUIDE.md line 706:

> 704: ### Preprocessor Definitions
> 705: 
> 706: C header files are processed by a pre-processor by a compiler before they are inspected

I think you mean pre-processor, and remove "by a compiler" ?

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

Marked as reviewed by mcimadamore (Reviewer).

PR Review: https://git.openjdk.org/jextract/pull/231#pullrequestreview-2003056787
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566997489
PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1566999472

From mcimadamore at openjdk.org  Tue Apr 16 09:03:06 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Tue, 16 Apr 2024 09:03:06 GMT
Subject: RFR: Add jextract guide [v12]
In-Reply-To: <sK69tgTQuczfpl48oVlorpd-TICIRpJBFEclU1Gi52M=.0cf8206e-757e-4dce-93e7-7bccdc6f2caa@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <iEJjiahjmE8sOYdMQom5y8ZjW_OeNR1Fcd-xjeU2hzo=.9571a32b-b921-4c4f-b1c6-41cb530d61cc@github.com>
 <sK69tgTQuczfpl48oVlorpd-TICIRpJBFEclU1Gi52M=.0cf8206e-757e-4dce-93e7-7bccdc6f2caa@github.com>
Message-ID: <ezSQzVb53bY4CIP-ErFn3Tut86XUqNvI9fMmR64fgbU=.a83a85da-641d-4a33-a5e5-7b7b0502b2fe@github.com>

On Tue, 16 Apr 2024 08:45:12 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Update doc/GUIDE.md
>>   
>>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>
> doc/GUIDE.md line 682:
> 
>> 680: 
>> 681: - Certain C types bigger than 64 bits (e.g. `long double` on Linux).
>> 682: - Function-like macros (as mentioned in the [section on constants](#constants-macros--enums))
> 
> I wonder if here we got the reference backwards - e.g. perhaps the section on constants should just say that function-like macros are not supported and point here, then here we could say what workarounds could be used in more details?

Errno and endianness also come to mind in terms of unsupported stuff

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

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

From jvernee at openjdk.org  Tue Apr 16 12:11:26 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 16 Apr 2024 12:11:26 GMT
Subject: RFR: Add jextract guide [v13]
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <-GZSJlCEeHvtaz3ksGwjo_eJ1UrQwG1QgoTRZCGNF5A=.b6040ae7-fcf5-4215-a0fa-e09bfb390e74@github.com>

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:

  Update doc/GUIDE.md
  
  Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/231/files
  - new: https://git.openjdk.org/jextract/pull/231/files/5de1f4fd..b5ab52c9

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=12
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=11-12

  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jextract/pull/231.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/231/head:pull/231

PR: https://git.openjdk.org/jextract/pull/231

From jvernee at openjdk.org  Tue Apr 16 13:03:04 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 16 Apr 2024 13:03:04 GMT
Subject: RFR: Add jextract guide [v12]
In-Reply-To: <OTgWvQFxjh7xQDmljyR5KmpZX6LyV2c25dIjkIoO3-M=.6b645e42-ee76-46ed-829c-adfcfa9e3ce5@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <iEJjiahjmE8sOYdMQom5y8ZjW_OeNR1Fcd-xjeU2hzo=.9571a32b-b921-4c4f-b1c6-41cb530d61cc@github.com>
 <OTgWvQFxjh7xQDmljyR5KmpZX6LyV2c25dIjkIoO3-M=.6b645e42-ee76-46ed-829c-adfcfa9e3ce5@github.com>
Message-ID: <t9KNwWcymUtDt9sW9VljmpGi5-z8d1JJK3uQbABCFp4=.ffec2a23-cfda-4abb-b4a7-b7e2df1d269f@github.com>

On Tue, 16 Apr 2024 08:27:17 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Update doc/GUIDE.md
>>   
>>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>
> doc/GUIDE.md line 10:
> 
>> 8: by loading a native library (e.g., a `.so`/`.dll`/`.dylib` file), which is essentially an
>> 9: archive of native functions and global variables. The user then has to look up the functions
>> 10: they want to call using a `SymbolLookup`, and finally _link_ the functions by using the
> 
> There's some classes and methods referenced here - should we use links? (don't have strong opinion)

I think so. This is introductory, so someone may want to read up on the FFM API before diving deeper in  jextract

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

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

From jvernee at openjdk.org  Tue Apr 16 13:29:02 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 16 Apr 2024 13:29:02 GMT
Subject: RFR: Add jextract guide [v12]
In-Reply-To: <UKHFHM2kPX9Bv2xkau1xqYCJU3MIeqNy8AEv_k5pJGE=.b3db5e44-cea7-4c58-a7e6-a377f1b12ae2@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <iEJjiahjmE8sOYdMQom5y8ZjW_OeNR1Fcd-xjeU2hzo=.9571a32b-b921-4c4f-b1c6-41cb530d61cc@github.com>
 <UKHFHM2kPX9Bv2xkau1xqYCJU3MIeqNy8AEv_k5pJGE=.b3db5e44-cea7-4c58-a7e6-a377f1b12ae2@github.com>
Message-ID: <FnuK-9CLBNtJQnOye4HaFLi-Nxf2Ll0N17cu3x7jDPU=.28e6bd51-e629-425c-a900-2130f585e8d8@github.com>

On Tue, 16 Apr 2024 08:55:14 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Update doc/GUIDE.md
>>   
>>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>
> doc/GUIDE.md line 676:
> 
>> 674: In the above snippet, note that the load of the `baz` field value on the last line will
>> 675: _see_ the update to the `bar` field of the `foo` instance on the line before.
>> 676: 
> 
> Perhaps we could also add a section (maybe in a followup PR) on fields/globals with array types, as jextract generates extra metadata (e.g. dimensions) and the Java type used for these accesses is MemorySegment (with bulk copy support on `set`)

Yes, good point. This was missed

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

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

From jvernee at openjdk.org  Tue Apr 16 13:29:03 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 16 Apr 2024 13:29:03 GMT
Subject: RFR: Add jextract guide [v12]
In-Reply-To: <FnuK-9CLBNtJQnOye4HaFLi-Nxf2Ll0N17cu3x7jDPU=.28e6bd51-e629-425c-a900-2130f585e8d8@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <iEJjiahjmE8sOYdMQom5y8ZjW_OeNR1Fcd-xjeU2hzo=.9571a32b-b921-4c4f-b1c6-41cb530d61cc@github.com>
 <UKHFHM2kPX9Bv2xkau1xqYCJU3MIeqNy8AEv_k5pJGE=.b3db5e44-cea7-4c58-a7e6-a377f1b12ae2@github.com>
 <FnuK-9CLBNtJQnOye4HaFLi-Nxf2Ll0N17cu3x7jDPU=.28e6bd51-e629-425c-a900-2130f585e8d8@github.com>
Message-ID: <gtx_qpt5HOKu7xFVyihhZfhyeBgN9T9IKVEr-VvEoKw=.d6935f26-dc7d-4ef2-be31-34508aebbdf4@github.com>

On Tue, 16 Apr 2024 13:24:44 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> doc/GUIDE.md line 676:
>> 
>>> 674: In the above snippet, note that the load of the `baz` field value on the last line will
>>> 675: _see_ the update to the `bar` field of the `foo` instance on the line before.
>>> 676: 
>> 
>> Perhaps we could also add a section (maybe in a followup PR) on fields/globals with array types, as jextract generates extra metadata (e.g. dimensions) and the Java type used for these accesses is MemorySegment (with bulk copy support on `set`)
>
> Yes, good point. This was missed

let's save this for a followup, and get this stake in the ground first :) (it will probably also be easier to review a small section)

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

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

From jvernee at openjdk.org  Tue Apr 16 13:36:35 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 16 Apr 2024 13:36:35 GMT
Subject: RFR: Add jextract guide [v14]
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <_dD-cr1yoC4icZLZqYgHss8PA3KoaXCQ5VLDz5bZ4hE=.f604b92e-eb52-49d0-9069-0ff31fa11207@github.com>

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

Jorn Vernee has updated the pull request incrementally with three additional commits since the last revision:

 - mor review comments
 - out-of-line javadoc links
 - more review comments

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/231/files
  - new: https://git.openjdk.org/jextract/pull/231/files/b5ab52c9..c3242781

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=13
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=231&range=12-13

  Stats: 99 lines in 2 files changed: 37 ins; 8 del; 54 mod
  Patch: https://git.openjdk.org/jextract/pull/231.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/231/head:pull/231

PR: https://git.openjdk.org/jextract/pull/231

From jvernee at openjdk.org  Tue Apr 16 13:42:02 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 16 Apr 2024 13:42:02 GMT
Subject: RFR: Add jextract guide [v14]
In-Reply-To: <_dD-cr1yoC4icZLZqYgHss8PA3KoaXCQ5VLDz5bZ4hE=.f604b92e-eb52-49d0-9069-0ff31fa11207@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <_dD-cr1yoC4icZLZqYgHss8PA3KoaXCQ5VLDz5bZ4hE=.f604b92e-eb52-49d0-9069-0ff31fa11207@github.com>
Message-ID: <weIyTlJVtZdbVIr8Xq-fGZrhPS8-hveTHhH7bPX1HF0=.91001bae-67d0-4c58-8c6b-32e8c7481670@github.com>

On Tue, 16 Apr 2024 13:36:35 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> Jorn Vernee has updated the pull request incrementally with three additional commits since the last revision:
> 
>  - mor review comments
>  - out-of-line javadoc links
>  - more review comments

I've address the last of the review comments. I've also move all the javadoc links out of line, since they are so long (and it might be nice to have them in one place, should we need to update them in the future).

I'll integrate this PR if there are no further comments. Thanks for the detailed review!

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

PR Comment: https://git.openjdk.org/jextract/pull/231#issuecomment-2059117294

From mcimadamore at openjdk.org  Tue Apr 16 13:57:03 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Tue, 16 Apr 2024 13:57:03 GMT
Subject: RFR: Add jextract guide [v14]
In-Reply-To: <_dD-cr1yoC4icZLZqYgHss8PA3KoaXCQ5VLDz5bZ4hE=.f604b92e-eb52-49d0-9069-0ff31fa11207@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
 <_dD-cr1yoC4icZLZqYgHss8PA3KoaXCQ5VLDz5bZ4hE=.f604b92e-eb52-49d0-9069-0ff31fa11207@github.com>
Message-ID: <03kb8cFUx5M-vEMbvWJQbg4jw7YpW_rvArDPP-AYSyM=.f8fcb041-0512-4b74-8d10-5e8e93878c4e@github.com>

On Tue, 16 Apr 2024 13:36:35 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> Jorn Vernee has updated the pull request incrementally with three additional commits since the last revision:
> 
>  - mor review comments
>  - out-of-line javadoc links
>  - more review comments

Marked as reviewed by mcimadamore (Reviewer).

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

PR Review: https://git.openjdk.org/jextract/pull/231#pullrequestreview-2003728957

From jvernee at openjdk.org  Tue Apr 16 14:09:04 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 16 Apr 2024 14:09:04 GMT
Subject: Integrated: Add jextract guide
In-Reply-To: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
References: <eDVn0L5ydOfhfKO5Vw-8rASLKhKJ1sB8jHALv-e5Ot0=.b205cb15-a97b-4fc6-b352-ca50089264c7@github.com>
Message-ID: <JK5FiwiWhUgu8NMTvmqmHUeCEoL1sD8rYWHt8jEhvJQ=.19c1e1ef-0750-44d2-82be-3ebc8f7b9e34@github.com>

On Tue, 9 Apr 2024 17:20:22 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Add a comprehensive jextract guide under a new `doc/` folder.
> 
> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
> 
> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.

This pull request has now been integrated.

Changeset: 7242f3e1
Author:    Jorn Vernee <jvernee at openjdk.org>
URL:       https://git.openjdk.org/jextract/commit/7242f3e1fd48fd74a5b1af486b9f3c8baba8f5e4
Stats:     1112 lines in 2 files changed: 941 ins; 171 del; 0 mod

Add jextract guide

Reviewed-by: mcimadamore

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

PR: https://git.openjdk.org/jextract/pull/231

From jvernee at openjdk.org  Tue Apr 16 16:22:20 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 16 Apr 2024 16:22:20 GMT
Subject: RFR: Add guide section about array types
Message-ID: <iFn7m8c-8AIB8JguogBb5VD0ELk52oQ2rI6LorR4e3M=.0cc2c58f-f070-4a07-9aa4-14d3950af4ae@github.com>

The current guide is missing a section discussing the special handling of array types, for which jextract generates a `$dimensions()` accessor, and indexed getters and setters.

This PR adds a section to the guide discussing this. I've put it at the end of the "Using The Code Generated By Jextract" section. I've put it before the section on nested types though, since it's a little more important I think.

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

Commit messages:
 - Add guide section about array types

Changes: https://git.openjdk.org/jextract/pull/236/files
  Webrev: https://webrevs.openjdk.org/?repo=jextract&pr=236&range=00
  Stats: 61 lines in 1 file changed: 61 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/jextract/pull/236.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/236/head:pull/236

PR: https://git.openjdk.org/jextract/pull/236

From mcimadamore at openjdk.org  Tue Apr 16 16:30:59 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Tue, 16 Apr 2024 16:30:59 GMT
Subject: RFR: Add guide section about array types
In-Reply-To: <iFn7m8c-8AIB8JguogBb5VD0ELk52oQ2rI6LorR4e3M=.0cc2c58f-f070-4a07-9aa4-14d3950af4ae@github.com>
References: <iFn7m8c-8AIB8JguogBb5VD0ELk52oQ2rI6LorR4e3M=.0cc2c58f-f070-4a07-9aa4-14d3950af4ae@github.com>
Message-ID: <CS3Qx_4o8IHzinvEhDoHp9e6RMGa48SfKuGkM3sPJl8=.cf080497-6cc0-4f6c-be2e-0386ee978e58@github.com>

On Tue, 16 Apr 2024 16:18:32 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> The current guide is missing a section discussing the special handling of array types, for which jextract generates a `$dimensions()` accessor, and indexed getters and setters.
> 
> This PR adds a section to the guide discussing this. I've put it at the end of the "Using The Code Generated By Jextract" section. I've put it before the section on nested types though, since it's a little more important I think.

doc/GUIDE.md line 641:

> 639: 1. a layout accessor, just like we have for a regular variable, but note that the return
> 640:   type is [`SequenceLayout`].
> 641: 2. a `$dimensions` meta-deta accessor, which returns the _dimensions_ of the array type.

Suggestion:

2. a `$dimensions` meta-data accessor, which returns the _dimensions_ of the array type.

doc/GUIDE.md line 643:

> 641: 2. a `$dimensions` meta-deta accessor, which returns the _dimensions_ of the array type.
> 642:   This method returns a `long[]` where each element represents the length of a dimension
> 643:   of the array type. For instance, in the example `FOO_ARRAY` has a two dimension, whose

Suggestion:

  of the array type. For instance, in the example `FOO_ARRAY` has two dimensions, whose

doc/GUIDE.md line 644:

> 642:   This method returns a `long[]` where each element represents the length of a dimension
> 643:   of the array type. For instance, in the example `FOO_ARRAY` has a two dimension, whose
> 644:   lengths are `3` and `5`, so the `FOO_ARRAY$dimensions` method will return a `long[]`

instead of "whose lengths are", I think it's better:
"has two dimensions - 3 and 5 respectively - ..."
(e.g. let's avoid talking about dimensions' length, which I don't think is very well defined)

doc/GUIDE.md line 646:

> 644:   lengths are `3` and `5`, so the `FOO_ARRAY$dimensions` method will return a `long[]`
> 645:   with two elements whose values are `3` and `5` in that order.
> 646: 3. a getter and setter pair for the array variable. Note that the getter replaces the usual

Should we start from this?

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

PR Review Comment: https://git.openjdk.org/jextract/pull/236#discussion_r1567651344
PR Review Comment: https://git.openjdk.org/jextract/pull/236#discussion_r1567651832
PR Review Comment: https://git.openjdk.org/jextract/pull/236#discussion_r1567653123
PR Review Comment: https://git.openjdk.org/jextract/pull/236#discussion_r1567648387

From jvernee at openjdk.org  Tue Apr 16 16:45:25 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 16 Apr 2024 16:45:25 GMT
Subject: RFR: Add guide section about array types [v2]
In-Reply-To: <iFn7m8c-8AIB8JguogBb5VD0ELk52oQ2rI6LorR4e3M=.0cc2c58f-f070-4a07-9aa4-14d3950af4ae@github.com>
References: <iFn7m8c-8AIB8JguogBb5VD0ELk52oQ2rI6LorR4e3M=.0cc2c58f-f070-4a07-9aa4-14d3950af4ae@github.com>
Message-ID: <CGoOKnhVDnEyLjhyb427ghpIB6makg6oXsrqFA5V0wg=.007a822b-0022-4f19-997e-b29f2be6635c@github.com>

> The current guide is missing a section discussing the special handling of array types, for which jextract generates a `$dimensions()` accessor, and indexed getters and setters.
> 
> This PR adds a section to the guide discussing this. I've put it at the end of the "Using The Code Generated By Jextract" section. I've put it before the section on nested types though, since it's a little more important I think.

Jorn Vernee has updated the pull request incrementally with three additional commits since the last revision:

 - review comments
 - Update doc/GUIDE.md
   
   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
 - Update doc/GUIDE.md
   
   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/236/files
  - new: https://git.openjdk.org/jextract/pull/236/files/d8dc0b6d..635d95f6

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=236&range=01
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=236&range=00-01

  Stats: 22 lines in 1 file changed: 7 ins; 7 del; 8 mod
  Patch: https://git.openjdk.org/jextract/pull/236.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/236/head:pull/236

PR: https://git.openjdk.org/jextract/pull/236

From jvernee at openjdk.org  Tue Apr 16 16:45:25 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 16 Apr 2024 16:45:25 GMT
Subject: RFR: Add guide section about array types [v2]
In-Reply-To: <CS3Qx_4o8IHzinvEhDoHp9e6RMGa48SfKuGkM3sPJl8=.cf080497-6cc0-4f6c-be2e-0386ee978e58@github.com>
References: <iFn7m8c-8AIB8JguogBb5VD0ELk52oQ2rI6LorR4e3M=.0cc2c58f-f070-4a07-9aa4-14d3950af4ae@github.com>
 <CS3Qx_4o8IHzinvEhDoHp9e6RMGa48SfKuGkM3sPJl8=.cf080497-6cc0-4f6c-be2e-0386ee978e58@github.com>
Message-ID: <4-jkNmKYRO0SbwTCR-pT3c3PhFaktjh9dW6VfC5N0A0=.dfbf9273-63ec-4cd8-a14f-ba08751436da@github.com>

On Tue, 16 Apr 2024 16:28:53 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with three additional commits since the last revision:
>> 
>>  - review comments
>>  - Update doc/GUIDE.md
>>    
>>    Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>>  - Update doc/GUIDE.md
>>    
>>    Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>
> doc/GUIDE.md line 644:
> 
>> 642:   This method returns a `long[]` where each element represents the length of a dimension
>> 643:   of the array type. For instance, in the example `FOO_ARRAY` has a two dimension, whose
>> 644:   lengths are `3` and `5`, so the `FOO_ARRAY$dimensions` method will return a `long[]`
> 
> instead of "whose lengths are", I think it's better:
> "has two dimensions - 3 and 5 respectively - ..."
> (e.g. let's avoid talking about dimensions' length, which I don't think is very well defined)

Yeah, good call.

> doc/GUIDE.md line 646:
> 
>> 644:   lengths are `3` and `5`, so the `FOO_ARRAY$dimensions` method will return a `long[]`
>> 645:   with two elements whose values are `3` and `5` in that order.
>> 646: 3. a getter and setter pair for the array variable. Note that the getter replaces the usual
> 
> Should we start from this?

I maintained the source order, but we can re-order (I did that for the function example as well). Getters/setters seem more important, so let's put them at the start.

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

PR Review Comment: https://git.openjdk.org/jextract/pull/236#discussion_r1567665433
PR Review Comment: https://git.openjdk.org/jextract/pull/236#discussion_r1567666115

From jvernee at openjdk.org  Tue Apr 16 17:04:10 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 16 Apr 2024 17:04:10 GMT
Subject: RFR: Add guide section about array types [v3]
In-Reply-To: <iFn7m8c-8AIB8JguogBb5VD0ELk52oQ2rI6LorR4e3M=.0cc2c58f-f070-4a07-9aa4-14d3950af4ae@github.com>
References: <iFn7m8c-8AIB8JguogBb5VD0ELk52oQ2rI6LorR4e3M=.0cc2c58f-f070-4a07-9aa4-14d3950af4ae@github.com>
Message-ID: <3jTV0ucL75XJL0M1dL7apINyv1J1NtISYOp84Dm2p2c=.38f28cac-c81f-4a46-8015-1b4c6d9a1bed@github.com>

> The current guide is missing a section discussing the special handling of array types, for which jextract generates a `$dimensions()` accessor, and indexed getters and setters.
> 
> This PR adds a section to the guide discussing this. I've put it at the end of the "Using The Code Generated By Jextract" section. I've put it before the section on nested types though, since it's a little more important I think.

Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:

  Fix samples link

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/236/files
  - new: https://git.openjdk.org/jextract/pull/236/files/635d95f6..821cc45d

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=236&range=02
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=236&range=01-02

  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jextract/pull/236.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/236/head:pull/236

PR: https://git.openjdk.org/jextract/pull/236

From jvernee at openjdk.org  Tue Apr 16 17:04:10 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 16 Apr 2024 17:04:10 GMT
Subject: RFR: Add guide section about array types [v2]
In-Reply-To: <CGoOKnhVDnEyLjhyb427ghpIB6makg6oXsrqFA5V0wg=.007a822b-0022-4f19-997e-b29f2be6635c@github.com>
References: <iFn7m8c-8AIB8JguogBb5VD0ELk52oQ2rI6LorR4e3M=.0cc2c58f-f070-4a07-9aa4-14d3950af4ae@github.com>
 <CGoOKnhVDnEyLjhyb427ghpIB6makg6oXsrqFA5V0wg=.007a822b-0022-4f19-997e-b29f2be6635c@github.com>
Message-ID: <2EYsshW7fXu7RvC6tzw8UgAQGtWu4ITFFtdXds7ePVA=.1a43fdc4-b512-4412-9e4f-a5a19cb2c6ad@github.com>

On Tue, 16 Apr 2024 16:45:25 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> The current guide is missing a section discussing the special handling of array types, for which jextract generates a `$dimensions()` accessor, and indexed getters and setters.
>> 
>> This PR adds a section to the guide discussing this. I've put it at the end of the "Using The Code Generated By Jextract" section. I've put it before the section on nested types though, since it's a little more important I think.
>
> Jorn Vernee has updated the pull request incrementally with three additional commits since the last revision:
> 
>  - review comments
>  - Update doc/GUIDE.md
>    
>    Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>  - Update doc/GUIDE.md
>    
>    Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>

I also noticed that the link to the samples is broken in the current text, so I've fixed this as well (https://github.com/openjdk/jextract/pull/236/commits/821cc45dcfc52282b80d4c13d69152b5722b1cc5)

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

PR Comment: https://git.openjdk.org/jextract/pull/236#issuecomment-2059544801

From mcimadamore at openjdk.org  Tue Apr 16 17:04:10 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Tue, 16 Apr 2024 17:04:10 GMT
Subject: RFR: Add guide section about array types [v2]
In-Reply-To: <CGoOKnhVDnEyLjhyb427ghpIB6makg6oXsrqFA5V0wg=.007a822b-0022-4f19-997e-b29f2be6635c@github.com>
References: <iFn7m8c-8AIB8JguogBb5VD0ELk52oQ2rI6LorR4e3M=.0cc2c58f-f070-4a07-9aa4-14d3950af4ae@github.com>
 <CGoOKnhVDnEyLjhyb427ghpIB6makg6oXsrqFA5V0wg=.007a822b-0022-4f19-997e-b29f2be6635c@github.com>
Message-ID: <Qy5SoBRQupY_IB92kmDprKX2zv4Z0doHOzCU8xpwCKY=.761aef95-8cd1-4b27-9122-7a5af5273181@github.com>

On Tue, 16 Apr 2024 16:45:25 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> The current guide is missing a section discussing the special handling of array types, for which jextract generates a `$dimensions()` accessor, and indexed getters and setters.
>> 
>> This PR adds a section to the guide discussing this. I've put it at the end of the "Using The Code Generated By Jextract" section. I've put it before the section on nested types though, since it's a little more important I think.
>
> Jorn Vernee has updated the pull request incrementally with three additional commits since the last revision:
> 
>  - review comments
>  - Update doc/GUIDE.md
>    
>    Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>  - Update doc/GUIDE.md
>    
>    Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>

doc/GUIDE.md line 619:

> 617: // mylib.h
> 618: 
> 619: int FOO_ARRAY[3][5];

Looking over the entire document, this is the only case where we use all caps. The other section on global variable uses lower case, so probably better to stick with that?

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

PR Review Comment: https://git.openjdk.org/jextract/pull/236#discussion_r1567689659

From mcimadamore at openjdk.org  Tue Apr 16 17:06:59 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Tue, 16 Apr 2024 17:06:59 GMT
Subject: RFR: Add guide section about array types [v2]
In-Reply-To: <CGoOKnhVDnEyLjhyb427ghpIB6makg6oXsrqFA5V0wg=.007a822b-0022-4f19-997e-b29f2be6635c@github.com>
References: <iFn7m8c-8AIB8JguogBb5VD0ELk52oQ2rI6LorR4e3M=.0cc2c58f-f070-4a07-9aa4-14d3950af4ae@github.com>
 <CGoOKnhVDnEyLjhyb427ghpIB6makg6oXsrqFA5V0wg=.007a822b-0022-4f19-997e-b29f2be6635c@github.com>
Message-ID: <A4wfNtNgKvs6YZ_bzXx9OF-U6AI4dGKmYN_W7KyTG7s=.1c95ffaf-804f-4a83-a8df-2614cf1d644c@github.com>

On Tue, 16 Apr 2024 16:45:25 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> The current guide is missing a section discussing the special handling of array types, for which jextract generates a `$dimensions()` accessor, and indexed getters and setters.
>> 
>> This PR adds a section to the guide discussing this. I've put it at the end of the "Using The Code Generated By Jextract" section. I've put it before the section on nested types though, since it's a little more important I think.
>
> Jorn Vernee has updated the pull request incrementally with three additional commits since the last revision:
> 
>  - review comments
>  - Update doc/GUIDE.md
>    
>    Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>  - Update doc/GUIDE.md
>    
>    Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>

Marked as reviewed by mcimadamore (Reviewer).

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

PR Review: https://git.openjdk.org/jextract/pull/236#pullrequestreview-2004191705

From jvernee at openjdk.org  Tue Apr 16 17:51:59 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 16 Apr 2024 17:51:59 GMT
Subject: Integrated: Add guide section about array types
In-Reply-To: <iFn7m8c-8AIB8JguogBb5VD0ELk52oQ2rI6LorR4e3M=.0cc2c58f-f070-4a07-9aa4-14d3950af4ae@github.com>
References: <iFn7m8c-8AIB8JguogBb5VD0ELk52oQ2rI6LorR4e3M=.0cc2c58f-f070-4a07-9aa4-14d3950af4ae@github.com>
Message-ID: <vfPuS8VqqYaegYLQTArwGFATh4sw8J4AOCuMmIKEGRI=.6000a390-a938-4c8a-a6fc-af69e0cd7f27@github.com>

On Tue, 16 Apr 2024 16:18:32 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> The current guide is missing a section discussing the special handling of array types, for which jextract generates a `$dimensions()` accessor, and indexed getters and setters.
> 
> This PR adds a section to the guide discussing this. I've put it at the end of the "Using The Code Generated By Jextract" section. I've put it before the section on nested types though, since it's a little more important I think.

This pull request has now been integrated.

Changeset: cde26650
Author:    Jorn Vernee <jvernee at openjdk.org>
URL:       https://git.openjdk.org/jextract/commit/cde2665007c9d56f427bf799c7152b6579ae4628
Stats:     62 lines in 1 file changed: 61 ins; 0 del; 1 mod

Add guide section about array types

Reviewed-by: mcimadamore

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

PR: https://git.openjdk.org/jextract/pull/236

From jvernee at openjdk.org  Tue Apr 16 17:51:59 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 16 Apr 2024 17:51:59 GMT
Subject: RFR: Add guide section about array types [v3]
In-Reply-To: <3jTV0ucL75XJL0M1dL7apINyv1J1NtISYOp84Dm2p2c=.38f28cac-c81f-4a46-8015-1b4c6d9a1bed@github.com>
References: <iFn7m8c-8AIB8JguogBb5VD0ELk52oQ2rI6LorR4e3M=.0cc2c58f-f070-4a07-9aa4-14d3950af4ae@github.com>
 <3jTV0ucL75XJL0M1dL7apINyv1J1NtISYOp84Dm2p2c=.38f28cac-c81f-4a46-8015-1b4c6d9a1bed@github.com>
Message-ID: <ACc8vUAPkzRh04aA110AOlkLznaZJjRga2CdZcwyzQg=.fcd9dc10-7dff-4cc5-bdae-ba94254a8921@github.com>

On Tue, 16 Apr 2024 17:04:10 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> The current guide is missing a section discussing the special handling of array types, for which jextract generates a `$dimensions()` accessor, and indexed getters and setters.
>> 
>> This PR adds a section to the guide discussing this. I've put it at the end of the "Using The Code Generated By Jextract" section. I've put it before the section on nested types though, since it's a little more important I think.
>
> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Fix samples link

Looks like the github actions broke again due to a jdk 22 version bump, resulting in different paths on mac (and windows too I think). Will take a look at the separately.

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

PR Comment: https://git.openjdk.org/jextract/pull/236#issuecomment-2059638453

From nlisker at gmail.com  Wed Apr 17 04:21:22 2024
From: nlisker at gmail.com (Nir Lisker)
Date: Wed, 17 Apr 2024 07:21:22 +0300
Subject: New guide --include-dir clarifications
Message-ID: <CA+0ynh8aD2o+jMN4fGxg9pEmYMp+Hnu4GdtdqeuXvOv+MG-z8w@mail.gmail.com>

Hi,

A couple of points regarding --include-dir in the guide that I think are
worth mentioning:
1. The directories are searched in order, so if the same header is found in
more than one included dirs, only the first one is taken. (I think this is
correct.)
2. The directories are *not* searched recursively. Nested directories need
to be added one by one if required.

If you agree that these should be added, I don't mind making a pull
request. I think it's best to add this info in the "Running jextract"
section.

- Nir
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jextract-dev/attachments/20240417/0c301310/attachment.htm>

From sundararajan.athijegannathan at oracle.com  Wed Apr 17 04:53:05 2024
From: sundararajan.athijegannathan at oracle.com (Sundararajan Athijegannathan)
Date: Wed, 17 Apr 2024 04:53:05 +0000
Subject: New guide --include-dir clarifications
In-Reply-To: <CA+0ynh8aD2o+jMN4fGxg9pEmYMp+Hnu4GdtdqeuXvOv+MG-z8w@mail.gmail.com>
References: <CA+0ynh8aD2o+jMN4fGxg9pEmYMp+Hnu4GdtdqeuXvOv+MG-z8w@mail.gmail.com>
Message-ID: <BL3PR10MB623407931B69948E1F1624CEEA0F2@BL3PR10MB6234.namprd10.prod.outlook.com>

Or should we just say that this is equivalent Clang compiler's -I option rather than repeating the specification in the jextract doc(s)/help?

BTW, even Clang's command line reference does not seem to specify/commit to the precise behavior seen/you mentioned...

https://clang.llvm.org/docs/ClangCommandLineReference.html

-Sundar
________________________________
From: jextract-dev <jextract-dev-retn at openjdk.org> on behalf of Nir Lisker <nlisker at gmail.com>
Sent: 17 April 2024 09:51
To: jextract-dev at openjdk.org <jextract-dev at openjdk.org>
Subject: New guide --include-dir clarifications

Hi,

A couple of points regarding --include-dir in the guide that I think are worth mentioning:
1. The directories are searched in order, so if the same header is found in more than one included dirs, only the first one is taken. (I think this is correct.)
2. The directories are *not* searched recursively. Nested directories need to be added one by one if required.

If you agree that these should be added, I don't mind making a pull request. I think it's best to add this info in the "Running jextract" section.

- Nir
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jextract-dev/attachments/20240417/6ee13e6e/attachment.htm>

From jorn.vernee at oracle.com  Wed Apr 17 10:39:55 2024
From: jorn.vernee at oracle.com (Jorn Vernee)
Date: Wed, 17 Apr 2024 12:39:55 +0200
Subject: New guide --include-dir clarifications
In-Reply-To: <BL3PR10MB623407931B69948E1F1624CEEA0F2@BL3PR10MB6234.namprd10.prod.outlook.com>
References: <CA+0ynh8aD2o+jMN4fGxg9pEmYMp+Hnu4GdtdqeuXvOv+MG-z8w@mail.gmail.com>
 <BL3PR10MB623407931B69948E1F1624CEEA0F2@BL3PR10MB6234.namprd10.prod.outlook.com>
Message-ID: <f6a89c72-4c25-4309-b747-eb07e870825e@oracle.com>

I think we could do a combination of the two: say that the value of the 
-I options is forwarded to clang (with a link to [1]), and then note the 
most important parts directly in the guide as well.


Jorn


[1]: 
https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-I-dir


On 17/04/2024 06:53, Sundararajan Athijegannathan wrote:
> Or should we just say that this is equivalent Clang compiler's -I 
> option rather than repeating the specification in the jextract 
> doc(s)/help?
>
> BTW, even Clang's command line reference does not seem to 
> specify/commit to the precise behavior seen/you mentioned...
>
> https://clang.llvm.org/docs/ClangCommandLineReference.html 
> <https://clang.llvm.org/docs/ClangCommandLineReference.html>
>
> -Sundar
> ------------------------------------------------------------------------
> *From:* jextract-dev <jextract-dev-retn at openjdk.org> on behalf of Nir 
> Lisker <nlisker at gmail.com>
> *Sent:* 17 April 2024 09:51
> *To:* jextract-dev at openjdk.org <jextract-dev at openjdk.org>
> *Subject:* New guide --include-dir clarifications
> Hi,
>
> A couple of points regarding --include-dir in the guide that I think 
> are worth mentioning:
> 1. The directories are searched in order, so if the same header is 
> found in more than one included dirs, only the first one is taken. (I 
> think this is correct.)
> 2. The directories are *not* searched recursively. Nested directories 
> need to be added one by one if required.
>
> If you agree that these should be added, I don't mind making a pull 
> request. I think it's best to add this info in?the "Running jextract" 
> section.
>
> - Nir
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jextract-dev/attachments/20240417/b0f36c32/attachment-0001.htm>

From jvernee at openjdk.org  Wed Apr 17 18:42:06 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Wed, 17 Apr 2024 18:42:06 GMT
Subject: RFR: Add guide section about platform-dependent nature of jextract
Message-ID: <Zfsuh9_WBTJtDV1ckaloViP2mCGTCAIIYm-5J8nisyY=.c750f042-2baf-4070-8491-19f1692121ee@github.com>

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

From mcimadamore at openjdk.org  Wed Apr 17 21:15:14 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 17 Apr 2024 21:15:14 GMT
Subject: RFR: Add guide section about platform-dependent nature of jextract
In-Reply-To: <Zfsuh9_WBTJtDV1ckaloViP2mCGTCAIIYm-5J8nisyY=.c750f042-2baf-4070-8491-19f1692121ee@github.com>
References: <Zfsuh9_WBTJtDV1ckaloViP2mCGTCAIIYm-5J8nisyY=.c750f042-2baf-4070-8491-19f1692121ee@github.com>
Message-ID: <uUMo06Dr_7mWygEE0VTyW_6HXGCp5kq9pgyOx106Me4=.b9d90090-2db1-4733-ad51-ee6b42a3c941@github.com>

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

From mcimadamore at openjdk.org  Wed Apr 17 21:15:23 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Wed, 17 Apr 2024 21:15:23 GMT
Subject: RFR: Add guide section about platform-dependent nature of jextract
In-Reply-To: <uUMo06Dr_7mWygEE0VTyW_6HXGCp5kq9pgyOx106Me4=.b9d90090-2db1-4733-ad51-ee6b42a3c941@github.com>
References: <Zfsuh9_WBTJtDV1ckaloViP2mCGTCAIIYm-5J8nisyY=.c750f042-2baf-4070-8491-19f1692121ee@github.com>
 <uUMo06Dr_7mWygEE0VTyW_6HXGCp5kq9pgyOx106Me4=.b9d90090-2db1-4733-ad51-ee6b42a3c941@github.com>
Message-ID: <fc3ocEhUv9kYeZdTGJiK44s6ELY3r7OnApOYL4gSMXE=.d2ceab0e-1d59-4fcf-aaa0-efed9f2644f9@github.com>

On Wed, 17 Apr 2024 21:06:04 GMT, Maurizio Cimadamore <mcimadamore 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

The above is to streamline things a bit (optional)

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

PR Review Comment: https://git.openjdk.org/jextract/pull/237#discussion_r1569555605

From pfeodrippe at gmail.com  Thu Apr 18 00:54:05 2024
From: pfeodrippe at gmail.com (Paulo Feodrippe)
Date: Wed, 17 Apr 2024 20:54:05 -0400
Subject: No subject
Message-ID: <CANDKcwDZaWLsj69ksKF6MnLhq=XzvSg8k74AhGsU385mCW3+6Q@mail.gmail.com>

Hi,

I'm using Build 22-jextract+3-13 and, while I'm able to jextract the
flecs.c file in https://github.com/SanderMertens/flecs, it generates a
param with the same name as one of the original params (allocator).

./src-java/org/vybe/flecs_2.java:7946: error: variable allocator is already
defined in method
ecs_vec_copy(java.lang.foreign.SegmentAllocator,java.lang.foreign.MemorySegment,java.lang.foreign.MemorySegment,int)
    public static MemorySegment ecs_vec_copy(SegmentAllocator allocator,
MemorySegment allocator, MemorySegment vec, int size) {

           ^
./src-java/org/vybe/flecs_2.java:7995: error: variable allocator is already
defined in method
ecs_vec_copy_shrink(java.lang.foreign.SegmentAllocator,java.lang.foreign.MemorySegment,java.lang.foreign.MemorySegment,int)
    public static MemorySegment ecs_vec_copy_shrink(SegmentAllocator
allocator, MemorySegment allocator, MemorySegment vec, int size) {

Thanks

-- 
Paulo Rafael Feodrippe,
Desenvolvedor
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jextract-dev/attachments/20240417/e016acac/attachment-0001.htm>

From maurizio.cimadamore at oracle.com  Thu Apr 18 10:00:56 2024
From: maurizio.cimadamore at oracle.com (Maurizio Cimadamore)
Date: Thu, 18 Apr 2024 11:00:56 +0100
Subject: No subject
In-Reply-To: <CANDKcwDZaWLsj69ksKF6MnLhq=XzvSg8k74AhGsU385mCW3+6Q@mail.gmail.com>
References: <CANDKcwDZaWLsj69ksKF6MnLhq=XzvSg8k74AhGsU385mCW3+6Q@mail.gmail.com>
Message-ID: <7d37daf5-9442-4e70-8446-f9d712aced6e@oracle.com>

Thanks for the report.

I've filed this: https://bugs.openjdk.org/browse/CODETOOLS-7903715

On 18/04/2024 01:54, Paulo Feodrippe wrote:
> Hi,
>
> I'm using Build 22-jextract+3-13 and, while I'm able to jextract the 
> flecs.c file in https://github.com/SanderMertens/flecs, it generates a 
> param with the same name as one of the original params (allocator).
>
> ./src-java/org/vybe/flecs_2.java:7946: error: variable allocator is 
> already defined in method 
> ecs_vec_copy(java.lang.foreign.SegmentAllocator,java.lang.foreign.MemorySegment,java.lang.foreign.MemorySegment,int)
> ? ? public static MemorySegment ecs_vec_copy(SegmentAllocator 
> allocator, MemorySegment allocator, MemorySegment vec, int size) {
> ? ? ? ? ? ? ? ? ? ? ? ? ?^
> ./src-java/org/vybe/flecs_2.java:7995: error: variable allocator is 
> already defined in method 
> ecs_vec_copy_shrink(java.lang.foreign.SegmentAllocator,java.lang.foreign.MemorySegment,java.lang.foreign.MemorySegment,int)
> ? ? public static MemorySegment ecs_vec_copy_shrink(SegmentAllocator 
> allocator, MemorySegment allocator, MemorySegment vec, int size) {
>
> Thanks
>
> -- 
> Paulo Rafael Feodrippe,
> Desenvolvedor
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jextract-dev/attachments/20240418/53d12a68/attachment.htm>

From mcimadamore at openjdk.org  Thu Apr 18 10:47:29 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Thu, 18 Apr 2024 10:47:29 GMT
Subject: RFR: 7903715: Jextract generates duplicate allocator parameters
Message-ID: <fOb3o0TSi05TNKTcj0Xa3FElogZMXzCqvv28vz0jBrA=.a3efe8b8-d34c-4948-ac9b-2f938d2b42e9@github.com>

This simple fix addresses a case where jextract generates two function parameter with duplicate name `allocator`.

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

Commit messages:
 - Initial push

Changes: https://git.openjdk.org/jextract/pull/238/files
  Webrev: https://webrevs.openjdk.org/?repo=jextract&pr=238&range=00
  Issue: https://bugs.openjdk.org/browse/CODETOOLS-7903715
  Stats: 75 lines in 3 files changed: 71 ins; 4 del; 0 mod
  Patch: https://git.openjdk.org/jextract/pull/238.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/238/head:pull/238

PR: https://git.openjdk.org/jextract/pull/238

From pfeodrippe at gmail.com  Thu Apr 18 11:05:28 2024
From: pfeodrippe at gmail.com (Paulo Feodrippe)
Date: Thu, 18 Apr 2024 07:05:28 -0400
Subject: No subject
In-Reply-To: <7d37daf5-9442-4e70-8446-f9d712aced6e@oracle.com>
References: <CANDKcwDZaWLsj69ksKF6MnLhq=XzvSg8k74AhGsU385mCW3+6Q@mail.gmail.com>
 <7d37daf5-9442-4e70-8446-f9d712aced6e@oracle.com>
Message-ID: <CANDKcwCBPxA0ej+ONdo4OaYQ0mZzB2_v8crD2bwykEu7db6R1w@mail.gmail.com>

Thank you very much, Maurizio, appreciate it :D

Great project you have here

Paulo Rafael Feodrippe,
Desenvolvedor


On Thu, Apr 18, 2024 at 6:01 AM Maurizio Cimadamore <
maurizio.cimadamore at oracle.com> wrote:

> Thanks for the report.
>
> I've filed this: https://bugs.openjdk.org/browse/CODETOOLS-7903715
> On 18/04/2024 01:54, Paulo Feodrippe wrote:
>
> Hi,
>
> I'm using Build 22-jextract+3-13 and, while I'm able to jextract the
> flecs.c file in https://github.com/SanderMertens/flecs, it generates a
> param with the same name as one of the original params (allocator).
>
> ./src-java/org/vybe/flecs_2.java:7946: error: variable allocator is
> already defined in method
> ecs_vec_copy(java.lang.foreign.SegmentAllocator,java.lang.foreign.MemorySegment,java.lang.foreign.MemorySegment,int)
>     public static MemorySegment ecs_vec_copy(SegmentAllocator allocator,
> MemorySegment allocator, MemorySegment vec, int size) {
>
>              ^
> ./src-java/org/vybe/flecs_2.java:7995: error: variable allocator is
> already defined in method
> ecs_vec_copy_shrink(java.lang.foreign.SegmentAllocator,java.lang.foreign.MemorySegment,java.lang.foreign.MemorySegment,int)
>     public static MemorySegment ecs_vec_copy_shrink(SegmentAllocator
> allocator, MemorySegment allocator, MemorySegment vec, int size) {
>
> Thanks
>
> --
> Paulo Rafael Feodrippe,
> Desenvolvedor
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jextract-dev/attachments/20240418/c7a05c7d/attachment-0001.htm>

From jvernee at openjdk.org  Thu Apr 18 12:46:21 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Thu, 18 Apr 2024 12:46:21 GMT
Subject: RFR: 7903715: Jextract generates duplicate allocator parameters
In-Reply-To: <fOb3o0TSi05TNKTcj0Xa3FElogZMXzCqvv28vz0jBrA=.a3efe8b8-d34c-4948-ac9b-2f938d2b42e9@github.com>
References: <fOb3o0TSi05TNKTcj0Xa3FElogZMXzCqvv28vz0jBrA=.a3efe8b8-d34c-4948-ac9b-2f938d2b42e9@github.com>
Message-ID: <hzJlVIlTQrayzVzXnbA_evJGepK6_4CkiQNMsqE4hG4=.706d07c5-0c37-47ae-996c-5fcc2dd88eb7@github.com>

On Thu, 18 Apr 2024 10:42:31 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This simple fix addresses a case where jextract generates two function parameter with duplicate name `allocator`.

Marked as reviewed by jvernee (Committer).

src/main/java/org/openjdk/jextract/impl/HeaderFileBuilder.java line 135:

> 133:             String allocatorName = "allocator";
> 134:             while (result.contains(allocatorName)) {
> 135:                 allocatorName = "_" + allocatorName;

In other places we've used `$` suffixes to deconflict names. Should we do the same here?

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

PR Review: https://git.openjdk.org/jextract/pull/238#pullrequestreview-2008785004
PR Review Comment: https://git.openjdk.org/jextract/pull/238#discussion_r1570659435

From jvernee at openjdk.org  Thu Apr 18 12:57:22 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Thu, 18 Apr 2024 12:57:22 GMT
Subject: RFR: Add guide section about platform-dependent nature of jextract
 [v2]
In-Reply-To: <Zfsuh9_WBTJtDV1ckaloViP2mCGTCAIIYm-5J8nisyY=.c750f042-2baf-4070-8491-19f1692121ee@github.com>
References: <Zfsuh9_WBTJtDV1ckaloViP2mCGTCAIIYm-5J8nisyY=.c750f042-2baf-4070-8491-19f1692121ee@github.com>
Message-ID: <gRXaplsDGItvOp5Fy5-yG7U7P9vnRhOlQhqbSD1smcE=.097c086c-f0b5-4334-a951-1b44e0b4dcf9@github.com>

> 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 at 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

From jvernee at openjdk.org  Thu Apr 18 12:57:22 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Thu, 18 Apr 2024 12:57:22 GMT
Subject: RFR: Add guide section about platform-dependent nature of jextract
 [v2]
In-Reply-To: <uUMo06Dr_7mWygEE0VTyW_6HXGCp5kq9pgyOx106Me4=.b9d90090-2db1-4733-ad51-ee6b42a3c941@github.com>
References: <Zfsuh9_WBTJtDV1ckaloViP2mCGTCAIIYm-5J8nisyY=.c750f042-2baf-4070-8491-19f1692121ee@github.com>
 <uUMo06Dr_7mWygEE0VTyW_6HXGCp5kq9pgyOx106Me4=.b9d90090-2db1-4733-ad51-ee6b42a3c941@github.com>
Message-ID: <oUEhcEeEqEIzgYMA7fmeV-Qx1AJFneCAzJbxNm-t8mY=.af697e20-2172-490b-be21-9aa95b83256c@github.com>

On Wed, 17 Apr 2024 21:05:40 GMT, Maurizio Cimadamore <mcimadamore at 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 at 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

From jvernee at openjdk.org  Thu Apr 18 13:03:35 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Thu, 18 Apr 2024 13:03:35 GMT
Subject: RFR: Add guide section about platform-dependent nature of jextract
 [v3]
In-Reply-To: <uUMo06Dr_7mWygEE0VTyW_6HXGCp5kq9pgyOx106Me4=.b9d90090-2db1-4733-ad51-ee6b42a3c941@github.com>
References: <Zfsuh9_WBTJtDV1ckaloViP2mCGTCAIIYm-5J8nisyY=.c750f042-2baf-4070-8491-19f1692121ee@github.com>
 <uUMo06Dr_7mWygEE0VTyW_6HXGCp5kq9pgyOx106Me4=.b9d90090-2db1-4733-ad51-ee6b42a3c941@github.com>
Message-ID: <GoLdMtn-OVso23gOWY2qn060fFxbKqhVLjqfnDKykQc=.b85e5d94-b54c-4fd5-9eed-c831170b1c23@github.com>

On Wed, 17 Apr 2024 21:04:52 GMT, Maurizio Cimadamore <mcimadamore at 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

From jvernee at openjdk.org  Thu Apr 18 13:03:34 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Thu, 18 Apr 2024 13:03:34 GMT
Subject: RFR: Add guide section about platform-dependent nature of jextract
 [v3]
In-Reply-To: <Zfsuh9_WBTJtDV1ckaloViP2mCGTCAIIYm-5J8nisyY=.c750f042-2baf-4070-8491-19f1692121ee@github.com>
References: <Zfsuh9_WBTJtDV1ckaloViP2mCGTCAIIYm-5J8nisyY=.c750f042-2baf-4070-8491-19f1692121ee@github.com>
Message-ID: <xQTWEuqXXx1sDNrxvFYLXeMHXa1uW44uUuglV_8UlxU=.b019d1ce-2f31-4d2c-88c2-2fecbb3c38f8@github.com>

> 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

From mcimadamore at openjdk.org  Thu Apr 18 13:09:07 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Thu, 18 Apr 2024 13:09:07 GMT
Subject: RFR: 7903715: Jextract generates duplicate allocator parameters
In-Reply-To: <hzJlVIlTQrayzVzXnbA_evJGepK6_4CkiQNMsqE4hG4=.706d07c5-0c37-47ae-996c-5fcc2dd88eb7@github.com>
References: <fOb3o0TSi05TNKTcj0Xa3FElogZMXzCqvv28vz0jBrA=.a3efe8b8-d34c-4948-ac9b-2f938d2b42e9@github.com>
 <hzJlVIlTQrayzVzXnbA_evJGepK6_4CkiQNMsqE4hG4=.706d07c5-0c37-47ae-996c-5fcc2dd88eb7@github.com>
Message-ID: <KZKSvPzpZVPMKb5-WWxLFZMZJZ7xRGTFSM3FBViQG-Y=.986834eb-9f2b-4a7e-9137-3fb52fa21c85@github.com>

On Thu, 18 Apr 2024 12:44:04 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> This simple fix addresses a case where jextract generates two function parameter with duplicate name `allocator`.
>
> src/main/java/org/openjdk/jextract/impl/HeaderFileBuilder.java line 135:
> 
>> 133:             String allocatorName = "allocator";
>> 134:             while (result.contains(allocatorName)) {
>> 135:                 allocatorName = "_" + allocatorName;
> 
> In other places we've used `$` suffixes to deconflict names. Should we do the same here?

I did this because the name mangler uses `_` when a name is a keyword e.g. `var`.

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

PR Review Comment: https://git.openjdk.org/jextract/pull/238#discussion_r1570706179

From mcimadamore at openjdk.org  Thu Apr 18 13:12:14 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Thu, 18 Apr 2024 13:12:14 GMT
Subject: RFR: Add guide section about platform-dependent nature of jextract
 [v3]
In-Reply-To: <xQTWEuqXXx1sDNrxvFYLXeMHXa1uW44uUuglV_8UlxU=.b019d1ce-2f31-4d2c-88c2-2fecbb3c38f8@github.com>
References: <Zfsuh9_WBTJtDV1ckaloViP2mCGTCAIIYm-5J8nisyY=.c750f042-2baf-4070-8491-19f1692121ee@github.com>
 <xQTWEuqXXx1sDNrxvFYLXeMHXa1uW44uUuglV_8UlxU=.b019d1ce-2f31-4d2c-88c2-2fecbb3c38f8@github.com>
Message-ID: <dFU4QzxTpVGC19tn9BzhbtnVCfIO_ZbjFSdAezwT0QM=.885608cc-31d2-4104-9f2e-7ca1b3986995@github.com>

On Thu, 18 Apr 2024 13:03:34 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.
>
> 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

From mcimadamore at openjdk.org  Thu Apr 18 13:30:11 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Thu, 18 Apr 2024 13:30:11 GMT
Subject: Integrated: 7903715: Jextract generates duplicate allocator parameters
In-Reply-To: <fOb3o0TSi05TNKTcj0Xa3FElogZMXzCqvv28vz0jBrA=.a3efe8b8-d34c-4948-ac9b-2f938d2b42e9@github.com>
References: <fOb3o0TSi05TNKTcj0Xa3FElogZMXzCqvv28vz0jBrA=.a3efe8b8-d34c-4948-ac9b-2f938d2b42e9@github.com>
Message-ID: <HSm_z3V5h13cTXA9zdISDuWc2d2IlN46yMbNtPD0Fho=.69583b0c-228b-4449-bf18-4161b006d5d0@github.com>

On Thu, 18 Apr 2024 10:42:31 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This simple fix addresses a case where jextract generates two function parameter with duplicate name `allocator`.

This pull request has now been integrated.

Changeset: 1cc982b6
Author:    Maurizio Cimadamore <mcimadamore at openjdk.org>
URL:       https://git.openjdk.org/jextract/commit/1cc982b6d4d9bfbbf8456fc86663592ee5c398c7
Stats:     75 lines in 3 files changed: 71 ins; 4 del; 0 mod

7903715: Jextract generates duplicate allocator parameters

Reviewed-by: jvernee

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

PR: https://git.openjdk.org/jextract/pull/238

From jvernee at openjdk.org  Thu Apr 18 13:36:10 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Thu, 18 Apr 2024 13:36:10 GMT
Subject: Integrated: Add guide section about platform-dependent nature of
 jextract
In-Reply-To: <Zfsuh9_WBTJtDV1ckaloViP2mCGTCAIIYm-5J8nisyY=.c750f042-2baf-4070-8491-19f1692121ee@github.com>
References: <Zfsuh9_WBTJtDV1ckaloViP2mCGTCAIIYm-5J8nisyY=.c750f042-2baf-4070-8491-19f1692121ee@github.com>
Message-ID: <5iu9Y39kZzGehf1nHCpvTHvUzo9STRVyI74UewDD2Pk=.72669630-20ed-4da0-8bdf-9364eb9a2d69@github.com>

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.

This pull request has now been integrated.

Changeset: 55ab7f4d
Author:    Jorn Vernee <jvernee at openjdk.org>
URL:       https://git.openjdk.org/jextract/commit/55ab7f4dbf38e65b18f80be2482fc1baa7077b2e
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

From jvernee at openjdk.org  Thu Apr 18 14:04:19 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Thu, 18 Apr 2024 14:04:19 GMT
Subject: RFR: Fix actions after version bump
Message-ID: <uMDRMLJCyViPqIa6NXuwRZFc3i9B-GDgcCtQlCfcFl4=.85ea99ef-5cf7-4859-ab78-0443249c76bd@github.com>

JDK bundles on different platforms have a different internal directory structure. We currently hard-code the path to the 'root' of the JDK (containing the `bin`/`lib`/`include` dirs, etc.) for each platform.

Recently the JDK version was bumped from 22 to 22.0.1, which changed the internal structure (since it includes the version in one of the directory names), thereby breaking our use of hard-coded paths.

This PR intends to fix this issue once and for all, by getting rid of the hard-coded paths. Instead, we try to find the `bin` folder within the downloaded package, and then copy the files from this discovered JDK root to a known location with a canonical path that is similar enough on each platform (this trick is borrowed from the mainline JDK GHA).

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

Commit messages:
 - Canonicallize toolchain structure

Changes: https://git.openjdk.org/jextract/pull/239/files
  Webrev: https://webrevs.openjdk.org/?repo=jextract&pr=239&range=00
  Stats: 20 lines in 1 file changed: 8 ins; 3 del; 9 mod
  Patch: https://git.openjdk.org/jextract/pull/239.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/239/head:pull/239

PR: https://git.openjdk.org/jextract/pull/239

From mcimadamore at openjdk.org  Thu Apr 18 14:41:09 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Thu, 18 Apr 2024 14:41:09 GMT
Subject: RFR: Fix actions after version bump
In-Reply-To: <uMDRMLJCyViPqIa6NXuwRZFc3i9B-GDgcCtQlCfcFl4=.85ea99ef-5cf7-4859-ab78-0443249c76bd@github.com>
References: <uMDRMLJCyViPqIa6NXuwRZFc3i9B-GDgcCtQlCfcFl4=.85ea99ef-5cf7-4859-ab78-0443249c76bd@github.com>
Message-ID: <AlY2u76Z2rVAX9dY8Vxrn-HrdxwRErK9hgKoSM62Ab4=.fa1f288b-2339-4ee2-9a39-2bad4346da77@github.com>

On Thu, 18 Apr 2024 14:00:07 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> JDK bundles on different platforms have a different internal directory structure. We currently hard-code the path to the 'root' of the JDK (containing the `bin`/`lib`/`include` dirs, etc.) for each platform.
> 
> Recently the JDK version was bumped from 22 to 22.0.1, which changed the internal structure (since it includes the version in one of the directory names), thereby breaking our use of hard-coded paths.
> 
> This PR intends to fix this issue once and for all, by getting rid of the hard-coded paths. Instead, we try to find the `bin` folder within the downloaded package, and then copy the files from this discovered JDK root to a known location with a canonical path that is similar enough on each platform (this trick is borrowed from the mainline JDK GHA).

Marked as reviewed by mcimadamore (Reviewer).

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

PR Review: https://git.openjdk.org/jextract/pull/239#pullrequestreview-2009103094

From jvernee at openjdk.org  Thu Apr 18 14:53:12 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Thu, 18 Apr 2024 14:53:12 GMT
Subject: Integrated: Fix actions after version bump
In-Reply-To: <uMDRMLJCyViPqIa6NXuwRZFc3i9B-GDgcCtQlCfcFl4=.85ea99ef-5cf7-4859-ab78-0443249c76bd@github.com>
References: <uMDRMLJCyViPqIa6NXuwRZFc3i9B-GDgcCtQlCfcFl4=.85ea99ef-5cf7-4859-ab78-0443249c76bd@github.com>
Message-ID: <DtNegWy_6T_C5YkG43DzEMWQupym9ylMhd42Z3mHY_c=.543a438c-ea0a-4eac-9aa9-ae84b7829f20@github.com>

On Thu, 18 Apr 2024 14:00:07 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> JDK bundles on different platforms have a different internal directory structure. We currently hard-code the path to the 'root' of the JDK (containing the `bin`/`lib`/`include` dirs, etc.) for each platform.
> 
> Recently the JDK version was bumped from 22 to 22.0.1, which changed the internal structure (since it includes the version in one of the directory names), thereby breaking our use of hard-coded paths.
> 
> This PR intends to fix this issue once and for all, by getting rid of the hard-coded paths. Instead, we try to find the `bin` folder within the downloaded package, and then copy the files from this discovered JDK root to a known location with a canonical path that is similar enough on each platform (this trick is borrowed from the mainline JDK GHA).

This pull request has now been integrated.

Changeset: 7fbd5c48
Author:    Jorn Vernee <jvernee at openjdk.org>
URL:       https://git.openjdk.org/jextract/commit/7fbd5c484c471b8ed16b9e4050f55c38840baae7
Stats:     20 lines in 1 file changed: 8 ins; 3 del; 9 mod

Fix actions after version bump

Reviewed-by: mcimadamore

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

PR: https://git.openjdk.org/jextract/pull/239

From thiago.sayao at gmail.com  Sun Apr 21 16:58:26 2024
From: thiago.sayao at gmail.com (=?UTF-8?Q?Thiago_Milczarek_Say=C3=A3o?=)
Date: Sun, 21 Apr 2024 13:58:26 -0300
Subject: jextract wayland-client
Message-ID: <CAAP_wu=r-ZZA9Quupz-GJeymeyECaDmqThvG2gvRUc5R5waUTA@mail.gmail.com>

Hi,

I'm trying to make a java wayland client (currently as a proof of concept).

I've attempted to generate the bindings like this:

jextract --output src -t org.freedesktop.wayland.client --header-class-name
WlClient -lwayland-client  /usr/include/wayland-client.h

But the wl_xxx types seem to not be supported as it outputs:

WARNING: Skipping wl_registry (type Declared(wl_registry) is not supported)

I've probably hit a current limitation. Is it expected to work in the
future?

Thanks.
-- Thiago.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jextract-dev/attachments/20240421/55fb8094/attachment.htm>

From jorn.vernee at oracle.com  Sun Apr 21 21:30:22 2024
From: jorn.vernee at oracle.com (Jorn Vernee)
Date: Sun, 21 Apr 2024 23:30:22 +0200
Subject: jextract wayland-client
In-Reply-To: <CAAP_wu=r-ZZA9Quupz-GJeymeyECaDmqThvG2gvRUc5R5waUTA@mail.gmail.com>
References: <CAAP_wu=r-ZZA9Quupz-GJeymeyECaDmqThvG2gvRUc5R5waUTA@mail.gmail.com>
Message-ID: <261ba798-181a-4b41-b952-8b7bc3b2a81e@oracle.com>

Hello Thiago,

It looks like the library you are using uses opaque types. Or, in other 
words, a type that is declared but not defined, such as:

struct Foo;

These types are not supported by jextract in the sense that the header 
file does not contain any definition for these types, so jextract also 
can't generate any code to access the fields of such a struct. This is 
not a current limitation of jextract, but a limitation imposed by the 
wayland library.

This is known as the 'opaque pointer idiom' [1]. It is a way of 
encapsulating the internals of a type, while still allowing a client to 
use it. It looks like the wayland library uses types like these in a lot 
of places. It doesn't mean that the library is unusable, it just means 
that the contents of these structs is not exposed by the library (and 
therefore /cannot/ be exposed by jextract). i.e. this is by design. You 
should still be able to use the library through the generated bindings.

I think for clarity we could perhaps change the warning message that 
jextract prints to something like:

 ??? WARNING: Skipping wl_registry (type Declared(wl_registry) is 
declared but not defined)

HTH,
Jorn

[1]: https://en.wikipedia.org/wiki/Opaque_pointer

On 21/04/2024 18:58, Thiago Milczarek Say?o wrote:
> Hi,
>
> I'm trying to make a java wayland client (currently as a proof of 
> concept).
>
> I've attempted to generate the bindings like this:
>
> jextract --output src -t org.freedesktop.wayland.client 
> --header-class-name WlClient -lwayland-client 
> ?/usr/include/wayland-client.h
>
> But the wl_xxx types seem to not be supported as it outputs:
>
> WARNING: Skipping wl_registry (type Declared(wl_registry) is not 
> supported)
>
> I've probably?hit a current limitation. Is it expected to work in the 
> future?
>
> Thanks.
> -- Thiago.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jextract-dev/attachments/20240421/8cff7334/attachment.htm>

From thiago.sayao at gmail.com  Sun Apr 21 22:51:33 2024
From: thiago.sayao at gmail.com (=?UTF-8?Q?Thiago_Milczarek_Say=C3=A3o?=)
Date: Sun, 21 Apr 2024 19:51:33 -0300
Subject: jextract wayland-client
In-Reply-To: <261ba798-181a-4b41-b952-8b7bc3b2a81e@oracle.com>
References: <CAAP_wu=r-ZZA9Quupz-GJeymeyECaDmqThvG2gvRUc5R5waUTA@mail.gmail.com>
 <261ba798-181a-4b41-b952-8b7bc3b2a81e@oracle.com>
Message-ID: <CAAP_wum0wy_Qvk0f9OmM_vW5frS_VO341O5n_GiPTjtcb3g7Ww@mail.gmail.com>

Hello Jorn,

Thanks for replying.

I think it's by design - those fields of wl_registry are private and only
accessible through wl_registry functions;

The problem is that it does not generate the functions that uses it, for
example wl_display_get_registry

I did:

jextract --output src/main/java -t org.freedesktop.wayland.client \
  --header-class-name WlClientProto `pkg-config --cflags-only-I
wayland-client` \
  `pkg-config --libs wayland-client`  \
  /usr/include/wayland-client-protocol.h


The clarified message looks good.

Em dom., 21 de abr. de 2024 ?s 18:30, Jorn Vernee <jorn.vernee at oracle.com>
escreveu:

> Hello Thiago,
>
> It looks like the library you are using uses opaque types. Or, in other
> words, a type that is declared but not defined, such as:
>
>     struct Foo;
>
> These types are not supported by jextract in the sense that the header
> file does not contain any definition for these types, so jextract also
> can't generate any code to access the fields of such a struct. This is not
> a current limitation of jextract, but a limitation imposed by the wayland
> library.
>
> This is known as the 'opaque pointer idiom' [1]. It is a way of
> encapsulating the internals of a type, while still allowing a client to use
> it. It looks like the wayland library uses types like these in a lot of
> places. It doesn't mean that the library is unusable, it just means that
> the contents of these structs is not exposed by the library (and therefore
> *cannot* be exposed by jextract). i.e. this is by design. You should
> still be able to use the library through the generated bindings.
>
> I think for clarity we could perhaps change the warning message that
> jextract prints to something like:
>
>     WARNING: Skipping wl_registry (type Declared(wl_registry) is declared
> but not defined)
>
> HTH,
> Jorn
>
> [1]: https://en.wikipedia.org/wiki/Opaque_pointer
> On 21/04/2024 18:58, Thiago Milczarek Say?o wrote:
>
> Hi,
>
> I'm trying to make a java wayland client (currently as a proof of concept).
>
> I've attempted to generate the bindings like this:
>
> jextract --output src -t org.freedesktop.wayland.client
> --header-class-name WlClient -lwayland-client  /usr/include/wayland-client.h
>
> But the wl_xxx types seem to not be supported as it outputs:
>
> WARNING: Skipping wl_registry (type Declared(wl_registry) is not supported)
>
> I've probably hit a current limitation. Is it expected to work in the
> future?
>
> Thanks.
> -- Thiago.
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jextract-dev/attachments/20240421/67fd5b6a/attachment-0001.htm>

From jorn.vernee at oracle.com  Sun Apr 21 23:25:30 2024
From: jorn.vernee at oracle.com (Jorn Vernee)
Date: Mon, 22 Apr 2024 01:25:30 +0200
Subject: [External] : Re: jextract wayland-client
In-Reply-To: <CAAP_wum0wy_Qvk0f9OmM_vW5frS_VO341O5n_GiPTjtcb3g7Ww@mail.gmail.com>
References: <CAAP_wu=r-ZZA9Quupz-GJeymeyECaDmqThvG2gvRUc5R5waUTA@mail.gmail.com>
 <261ba798-181a-4b41-b952-8b7bc3b2a81e@oracle.com>
 <CAAP_wum0wy_Qvk0f9OmM_vW5frS_VO341O5n_GiPTjtcb3g7Ww@mail.gmail.com>
Message-ID: <b8012a0c-ded7-4ad4-b63d-c31c5ab814cd@oracle.com>

A pointer type is always supported, so it should not prevent a function 
that uses such a type from being generated.

Are you seeing any warnings about `wl_display_get_registry` being 
skipped because of an unsupported type?

Could you shared the header file declaration of wl_display_get_registry?

Jorn

On 22/04/2024 00:51, Thiago Milczarek Say?o wrote:
> Hello Jorn,
>
> Thanks for replying.
>
> I think it's by design -?those fields of wl_registry are private and 
> only accessible?through wl_registry functions;
>
> The problem is that it does not generate the functions that uses it, 
> for example?wl_display_get_registry
>
> I did:
> jextract --output src/main/java -t org.freedesktop.wayland.client \
>    --header-class-name WlClientProto`pkg-config --cflags-only-I wayland-client`  \
>    `pkg-config --libs wayland-client`   \
>    /usr/include/wayland-client-protocol.h
>
> The clarified message looks good.
>
> Em dom., 21 de abr. de 2024 ?s 18:30, Jorn Vernee 
> <jorn.vernee at oracle.com> escreveu:
>
>     Hello Thiago,
>
>     It looks like the library you are using uses opaque types. Or, in
>     other words, a type that is declared but not defined, such as:
>
>     struct Foo;
>
>     These types are not supported by jextract in the sense that the
>     header file does not contain any definition for these types, so
>     jextract also can't generate any code to access the fields of such
>     a struct. This is not a current limitation of jextract, but a
>     limitation imposed by the wayland library.
>
>     This is known as the 'opaque pointer idiom' [1]. It is a way of
>     encapsulating the internals of a type, while still allowing a
>     client to use it. It looks like the wayland library uses types
>     like these in a lot of places. It doesn't mean that the library is
>     unusable, it just means that the contents of these structs is not
>     exposed by the library (and therefore /cannot/ be exposed by
>     jextract). i.e. this is by design. You should still be able to use
>     the library through the generated bindings.
>
>     I think for clarity we could perhaps change the warning message
>     that jextract prints to something like:
>
>     ??? WARNING: Skipping wl_registry (type Declared(wl_registry) is
>     declared but not defined)
>
>     HTH,
>     Jorn
>
>     [1]: https://en.wikipedia.org/wiki/Opaque_pointer
>     <https://urldefense.com/v3/__https://en.wikipedia.org/wiki/Opaque_pointer__;!!ACWV5N9M2RV99hQ!J7UcZ_pVCMYJLfWJp9TZNELYAFrerMmP-yIjI1X6pBl6Zfx8gKLGiEb8ESgd_FTELrMqKd0F8pBF_Zs6zquT91c$>
>
>     On 21/04/2024 18:58, Thiago Milczarek Say?o wrote:
>>     Hi,
>>
>>     I'm trying to make a java wayland client (currently as a proof of
>>     concept).
>>
>>     I've attempted to generate the bindings like this:
>>
>>     jextract --output src -t org.freedesktop.wayland.client
>>     --header-class-name WlClient -lwayland-client
>>     ?/usr/include/wayland-client.h
>>
>>     But the wl_xxx types seem to not be supported as it outputs:
>>
>>     WARNING: Skipping wl_registry (type Declared(wl_registry) is not
>>     supported)
>>
>>     I've probably?hit a current limitation. Is it expected to work in
>>     the future?
>>
>>     Thanks.
>>     -- Thiago.
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jextract-dev/attachments/20240422/3146b232/attachment.htm>

From thiago.sayao at gmail.com  Sun Apr 21 23:36:03 2024
From: thiago.sayao at gmail.com (=?UTF-8?Q?Thiago_Milczarek_Say=C3=A3o?=)
Date: Sun, 21 Apr 2024 20:36:03 -0300
Subject: [External] : Re: jextract wayland-client
In-Reply-To: <b8012a0c-ded7-4ad4-b63d-c31c5ab814cd@oracle.com>
References: <CAAP_wu=r-ZZA9Quupz-GJeymeyECaDmqThvG2gvRUc5R5waUTA@mail.gmail.com>
 <261ba798-181a-4b41-b952-8b7bc3b2a81e@oracle.com>
 <CAAP_wum0wy_Qvk0f9OmM_vW5frS_VO341O5n_GiPTjtcb3g7Ww@mail.gmail.com>
 <b8012a0c-ded7-4ad4-b63d-c31c5ab814cd@oracle.com>
Message-ID: <CAAP_wun=ankpL4LW=b7R-unFQuq_6FyKd3qnd3KAtE1d-jrduQ@mail.gmail.com>

Humm,

It an inline function:

static inline struct wl_registry *
wl_display_get_registry(struct wl_display *wl_display)
{
        struct wl_proxy *registry;

        registry = wl_proxy_marshal_flags((struct wl_proxy *) wl_display,
                         WL_DISPLAY_GET_REGISTRY,
&wl_registry_interface, wl_proxy_get_version((struct wl_proxy *)
wl_display), 0, NULL);

        return (struct wl_registry *) registry;
}


Em dom., 21 de abr. de 2024 ?s 20:25, Jorn Vernee <jorn.vernee at oracle.com>
escreveu:

> A pointer type is always supported, so it should not prevent a function
> that uses such a type from being generated.
>
> Are you seeing any warnings about `wl_display_get_registry` being skipped
> because of an unsupported type?
>
> Could you shared the header file declaration of wl_display_get_registry?
>
> Jorn
> On 22/04/2024 00:51, Thiago Milczarek Say?o wrote:
>
> Hello Jorn,
>
> Thanks for replying.
>
> I think it's by design - those fields of wl_registry are private and only
> accessible through wl_registry functions;
>
> The problem is that it does not generate the functions that uses it, for
> example wl_display_get_registry
>
> I did:
>
> jextract --output src/main/java -t org.freedesktop.wayland.client \
>   --header-class-name WlClientProto `pkg-config --cflags-only-I wayland-client` \
>   `pkg-config --libs wayland-client`  \
>   /usr/include/wayland-client-protocol.h
>
>
> The clarified message looks good.
>
> Em dom., 21 de abr. de 2024 ?s 18:30, Jorn Vernee <jorn.vernee at oracle.com>
> escreveu:
>
>> Hello Thiago,
>>
>> It looks like the library you are using uses opaque types. Or, in other
>> words, a type that is declared but not defined, such as:
>>
>>     struct Foo;
>>
>> These types are not supported by jextract in the sense that the header
>> file does not contain any definition for these types, so jextract also
>> can't generate any code to access the fields of such a struct. This is not
>> a current limitation of jextract, but a limitation imposed by the wayland
>> library.
>>
>> This is known as the 'opaque pointer idiom' [1]. It is a way of
>> encapsulating the internals of a type, while still allowing a client to use
>> it. It looks like the wayland library uses types like these in a lot of
>> places. It doesn't mean that the library is unusable, it just means that
>> the contents of these structs is not exposed by the library (and therefore
>> *cannot* be exposed by jextract). i.e. this is by design. You should
>> still be able to use the library through the generated bindings.
>>
>> I think for clarity we could perhaps change the warning message that
>> jextract prints to something like:
>>
>>     WARNING: Skipping wl_registry (type Declared(wl_registry) is declared
>> but not defined)
>>
>> HTH,
>> Jorn
>>
>> [1]: https://en.wikipedia.org/wiki/Opaque_pointer
>> <https://urldefense.com/v3/__https://en.wikipedia.org/wiki/Opaque_pointer__;!!ACWV5N9M2RV99hQ!J7UcZ_pVCMYJLfWJp9TZNELYAFrerMmP-yIjI1X6pBl6Zfx8gKLGiEb8ESgd_FTELrMqKd0F8pBF_Zs6zquT91c$>
>> On 21/04/2024 18:58, Thiago Milczarek Say?o wrote:
>>
>> Hi,
>>
>> I'm trying to make a java wayland client (currently as a proof of
>> concept).
>>
>> I've attempted to generate the bindings like this:
>>
>> jextract --output src -t org.freedesktop.wayland.client
>> --header-class-name WlClient -lwayland-client  /usr/include/wayland-client.h
>>
>> But the wl_xxx types seem to not be supported as it outputs:
>>
>> WARNING: Skipping wl_registry (type Declared(wl_registry) is not
>> supported)
>>
>> I've probably hit a current limitation. Is it expected to work in the
>> future?
>>
>> Thanks.
>> -- Thiago.
>>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jextract-dev/attachments/20240421/0b377c45/attachment-0001.htm>

From jorn.vernee at oracle.com  Sun Apr 21 23:46:28 2024
From: jorn.vernee at oracle.com (Jorn Vernee)
Date: Mon, 22 Apr 2024 01:46:28 +0200
Subject: [External] : Re: jextract wayland-client
In-Reply-To: <CAAP_wun=ankpL4LW=b7R-unFQuq_6FyKd3qnd3KAtE1d-jrduQ@mail.gmail.com>
References: <CAAP_wu=r-ZZA9Quupz-GJeymeyECaDmqThvG2gvRUc5R5waUTA@mail.gmail.com>
 <261ba798-181a-4b41-b952-8b7bc3b2a81e@oracle.com>
 <CAAP_wum0wy_Qvk0f9OmM_vW5frS_VO341O5n_GiPTjtcb3g7Ww@mail.gmail.com>
 <b8012a0c-ded7-4ad4-b63d-c31c5ab814cd@oracle.com>
 <CAAP_wun=ankpL4LW=b7R-unFQuq_6FyKd3qnd3KAtE1d-jrduQ@mail.gmail.com>
Message-ID: <df7b2593-690b-4044-a533-ca2af38f66a0@oracle.com>

The function is also 'static'. Static functions are typically not 
exported from the runtime library, so we can not link against them 
dynamically (which is required for a function to be callable from Java). 
You might want to confirm by running e.g. `nm <runtime library>` that 
this function is actually an exported symbol in the library.

Alternatively, you might be able to re-write this function in Java using 
the parts of the library that are exported/dynamically link-able.

Jorn

On 22/04/2024 01:36, Thiago Milczarek Say?o wrote:
> Humm,
>
> It an inline function:
>
> static inline struct wl_registry *
> wl_display_get_registry(struct wl_display *wl_display)
> {
>          struct wl_proxy *registry;
>
>          registry = wl_proxy_marshal_flags((struct wl_proxy *) wl_display,
>                           WL_DISPLAY_GET_REGISTRY, &wl_registry_interface, wl_proxy_get_version((struct wl_proxy *) wl_display),0, NULL);
>
>          return (struct wl_registry *) registry;
> }
>
> Em dom., 21 de abr. de 2024 ?s 20:25, Jorn Vernee 
> <jorn.vernee at oracle.com> escreveu:
>
>     A pointer type is always supported, so it should not prevent a
>     function that uses such a type from being generated.
>
>     Are you seeing any warnings about `wl_display_get_registry` being
>     skipped because of an unsupported type?
>
>     Could you shared the header file declaration of
>     wl_display_get_registry?
>
>     Jorn
>
>     On 22/04/2024 00:51, Thiago Milczarek Say?o wrote:
>>     Hello Jorn,
>>
>>     Thanks for replying.
>>
>>     I think it's by design -?those fields of wl_registry are private
>>     and only accessible?through wl_registry functions;
>>
>>     The problem is that it does not generate the functions that uses
>>     it, for example?wl_display_get_registry
>>
>>     I did:
>>     jextract --output src/main/java -t org.freedesktop.wayland.client \
>>        --header-class-name WlClientProto`pkg-config --cflags-only-I wayland-client`  \
>>        `pkg-config --libs wayland-client`   \
>>        /usr/include/wayland-client-protocol.h
>>
>>     The clarified message looks good.
>>
>>     Em dom., 21 de abr. de 2024 ?s 18:30, Jorn Vernee
>>     <jorn.vernee at oracle.com> escreveu:
>>
>>         Hello Thiago,
>>
>>         It looks like the library you are using uses opaque types.
>>         Or, in other words, a type that is declared but not defined,
>>         such as:
>>
>>         struct Foo;
>>
>>         These types are not supported by jextract in the sense that
>>         the header file does not contain any definition for these
>>         types, so jextract also can't generate any code to access the
>>         fields of such a struct. This is not a current limitation of
>>         jextract, but a limitation imposed by the wayland library.
>>
>>         This is known as the 'opaque pointer idiom' [1]. It is a way
>>         of encapsulating the internals of a type, while still
>>         allowing a client to use it. It looks like the wayland
>>         library uses types like these in a lot of places. It doesn't
>>         mean that the library is unusable, it just means that the
>>         contents of these structs is not exposed by the library (and
>>         therefore /cannot/ be exposed by jextract). i.e. this is by
>>         design. You should still be able to use the library through
>>         the generated bindings.
>>
>>         I think for clarity we could perhaps change the warning
>>         message that jextract prints to something like:
>>
>>         ??? WARNING: Skipping wl_registry (type Declared(wl_registry)
>>         is declared but not defined)
>>
>>         HTH,
>>         Jorn
>>
>>         [1]: https://en.wikipedia.org/wiki/Opaque_pointer
>>         <https://urldefense.com/v3/__https://en.wikipedia.org/wiki/Opaque_pointer__;!!ACWV5N9M2RV99hQ!J7UcZ_pVCMYJLfWJp9TZNELYAFrerMmP-yIjI1X6pBl6Zfx8gKLGiEb8ESgd_FTELrMqKd0F8pBF_Zs6zquT91c$>
>>
>>         On 21/04/2024 18:58, Thiago Milczarek Say?o wrote:
>>>         Hi,
>>>
>>>         I'm trying to make a java wayland client (currently as a
>>>         proof of concept).
>>>
>>>         I've attempted to generate the bindings like this:
>>>
>>>         jextract --output src -t org.freedesktop.wayland.client
>>>         --header-class-name WlClient -lwayland-client
>>>         ?/usr/include/wayland-client.h
>>>
>>>         But the wl_xxx types seem to not be supported as it outputs:
>>>
>>>         WARNING: Skipping wl_registry (type Declared(wl_registry) is
>>>         not supported)
>>>
>>>         I've probably?hit a current limitation. Is it expected to
>>>         work in the future?
>>>
>>>         Thanks.
>>>         -- Thiago.
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jextract-dev/attachments/20240422/b0eabe25/attachment.htm>

From jvernee at openjdk.org  Tue Apr 30 14:53:26 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 30 Apr 2024 14:53:26 GMT
Subject: RFR: 7903720: Change layout of jextract image
Message-ID: <FmvCKWrTOm4Y2WBZj6L-5Q5jEf8ioceekySRvJP0BBA=.5e24425f-b1d9-4cf9-9957-0aa98ab47b27@github.com>

See JBS issue for problem description.

This patch changes the layout of the jextract image we produce. The new image has the 2 launcher scripts in the root of the image, with a nested `runtime` folder containing the jlink runtime image.

I've added both launcher scripts to the repo under the `src/main` directory, and they are copied to the image during the build. The script is somewhat simplified by removing a blank variable that was not being used. I also took the opportunity to address an issue with the windows launcher script turning off `echo`. Instead it now avoids output using the `@` prefix for each command in the script.

I've tested that the scripts work (using `jextract --help`) on both Linux and Windows.

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

Commit messages:
 - remove spurious imports
 - update verify task
 - Improve image layout and launcher scripts

Changes: https://git.openjdk.org/jextract/pull/241/files
  Webrev: https://webrevs.openjdk.org/?repo=jextract&pr=241&range=00
  Issue: https://bugs.openjdk.org/browse/CODETOOLS-7903720
  Stats: 18 lines in 4 files changed: 12 ins; 1 del; 5 mod
  Patch: https://git.openjdk.org/jextract/pull/241.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/241/head:pull/241

PR: https://git.openjdk.org/jextract/pull/241

From mcimadamore at openjdk.org  Tue Apr 30 15:00:19 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Tue, 30 Apr 2024 15:00:19 GMT
Subject: RFR: 7903720: Change layout of jextract image
In-Reply-To: <FmvCKWrTOm4Y2WBZj6L-5Q5jEf8ioceekySRvJP0BBA=.5e24425f-b1d9-4cf9-9957-0aa98ab47b27@github.com>
References: <FmvCKWrTOm4Y2WBZj6L-5Q5jEf8ioceekySRvJP0BBA=.5e24425f-b1d9-4cf9-9957-0aa98ab47b27@github.com>
Message-ID: <NQPm39yMNfZnFAqfKXUuAkqVm_X-Oqb8WdKNbrMpuvQ=.69c5f5e3-9153-4ef4-9c02-760006508162@github.com>

On Tue, 30 Apr 2024 14:49:25 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> See JBS issue for problem description.
> 
> This patch changes the layout of the jextract image we produce. The new image has the 2 launcher scripts in the root of the image, with a nested `runtime` folder containing the jlink runtime image.
> 
> I've added both launcher scripts to the repo under the `src/main` directory, and they are copied to the image during the build. The script is somewhat simplified by removing a blank variable that was not being used. I also took the opportunity to address an issue with the windows launcher script turning off `echo`. Instead it now avoids output using the `@` prefix for each command in the script.
> 
> I've tested that the scripts work (using `jextract --help`) on both Linux and Windows.

Marked as reviewed by mcimadamore (Reviewer).

src/main/jextract line 3:

> 1: #!/bin/sh
> 2: DIR=`dirname $0`
> 3: $DIR/runtime/bin/java -m org.openjdk.jextract/org.openjdk.jextract.JextractTool "$@"

What do you think about adding a dependency on some shell variable (e.g. JEXTRACT_JAVA_OPTIONS) to pass extra arguments to jextract's JVM? I recall reaching for something like this e.g. to enable debug mode? (But, totally optional, more asking for an opinion)

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

PR Review: https://git.openjdk.org/jextract/pull/241#pullrequestreview-2031643253
PR Review Comment: https://git.openjdk.org/jextract/pull/241#discussion_r1584981216

From jvernee at openjdk.org  Tue Apr 30 15:43:20 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 30 Apr 2024 15:43:20 GMT
Subject: RFR: 7903720: Change layout of jextract image
In-Reply-To: <NQPm39yMNfZnFAqfKXUuAkqVm_X-Oqb8WdKNbrMpuvQ=.69c5f5e3-9153-4ef4-9c02-760006508162@github.com>
References: <FmvCKWrTOm4Y2WBZj6L-5Q5jEf8ioceekySRvJP0BBA=.5e24425f-b1d9-4cf9-9957-0aa98ab47b27@github.com>
 <NQPm39yMNfZnFAqfKXUuAkqVm_X-Oqb8WdKNbrMpuvQ=.69c5f5e3-9153-4ef4-9c02-760006508162@github.com>
Message-ID: <bne2v6JOXeQ41Wn11spQJTSnmMj-yeVSzdRd7C9VXZU=.0d563058-f56d-4342-abab-1df1ab365a44@github.com>

On Tue, 30 Apr 2024 14:57:43 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> See JBS issue for problem description.
>> 
>> This patch changes the layout of the jextract image we produce. The new image has the 2 launcher scripts in the root of the image, with a nested `runtime` folder containing the jlink runtime image.
>> 
>> I've added both launcher scripts to the repo under the `src/main` directory, and they are copied to the image during the build. The script is somewhat simplified by removing a blank variable that was not being used. I also took the opportunity to address an issue with the windows launcher script turning off `echo`. Instead it now avoids output using the `@` prefix for each command in the script.
>> 
>> I've tested that the scripts work (using `jextract --help`) on both Linux and Windows.
>
> src/main/jextract line 3:
> 
>> 1: #!/bin/sh
>> 2: DIR=`dirname $0`
>> 3: $DIR/runtime/bin/java -m org.openjdk.jextract/org.openjdk.jextract.JextractTool "$@"
> 
> What do you think about adding a dependency on some shell variable (e.g. JEXTRACT_JAVA_OPTIONS) to pass extra arguments to jextract's JVM? I recall reaching for something like this e.g. to enable debug mode? (But, totally optional, more asking for an opinion)

Yes, this seems like a good idea.

Previously I would just modify the launch script.

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

PR Review Comment: https://git.openjdk.org/jextract/pull/241#discussion_r1585076535

From jvernee at openjdk.org  Tue Apr 30 16:27:27 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 30 Apr 2024 16:27:27 GMT
Subject: RFR: 7903720: Change layout of jextract image [v2]
In-Reply-To: <FmvCKWrTOm4Y2WBZj6L-5Q5jEf8ioceekySRvJP0BBA=.5e24425f-b1d9-4cf9-9957-0aa98ab47b27@github.com>
References: <FmvCKWrTOm4Y2WBZj6L-5Q5jEf8ioceekySRvJP0BBA=.5e24425f-b1d9-4cf9-9957-0aa98ab47b27@github.com>
Message-ID: <IQN1STbQ-sOmgTWoLYLRl7fmuqNhytGVguDGG3OLBDQ=.9e2286e6-6591-4408-b62d-b9866dc53ea7@github.com>

> See JBS issue for problem description.
> 
> This patch changes the layout of the jextract image we produce. The new image has the 2 launcher scripts in the root of the image, with a nested `runtime` folder containing the jlink runtime image.
> 
> I've added both launcher scripts to the repo under the `src/main` directory, and they are copied to the image during the build. The script is somewhat simplified by removing a blank variable that was not being used. I also took the opportunity to address an issue with the windows launcher script turning off `echo`. Instead it now avoids output using the `@` prefix for each command in the script.
> 
> I've tested that the scripts work (using `jextract --help`) on both Linux and Windows.

Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:

  set file permissions to executable for jextract script

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/241/files
  - new: https://git.openjdk.org/jextract/pull/241/files/75998f5d..712670c3

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=241&range=01
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=241&range=00-01

  Stats: 0 lines in 1 file changed: 0 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/jextract/pull/241.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/241/head:pull/241

PR: https://git.openjdk.org/jextract/pull/241

From jvernee at openjdk.org  Tue Apr 30 16:53:44 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 30 Apr 2024 16:53:44 GMT
Subject: RFR: 7903720: Change layout of jextract image [v3]
In-Reply-To: <FmvCKWrTOm4Y2WBZj6L-5Q5jEf8ioceekySRvJP0BBA=.5e24425f-b1d9-4cf9-9957-0aa98ab47b27@github.com>
References: <FmvCKWrTOm4Y2WBZj6L-5Q5jEf8ioceekySRvJP0BBA=.5e24425f-b1d9-4cf9-9957-0aa98ab47b27@github.com>
Message-ID: <QDstfE7ySqg4Z_nEEDqWNKhNPRI0nRwD8-0Q-jl_AHY=.ec20b321-b2dd-421d-b368-8eccaa4ae1ce@github.com>

> See JBS issue for problem description.
> 
> This patch changes the layout of the jextract image we produce. The new image has the 2 launcher scripts in the root of the image, with a nested `runtime` folder containing the jlink runtime image.
> 
> I've added both launcher scripts to the repo under the `src/main` directory, and they are copied to the image during the build. The script is somewhat simplified by removing a blank variable that was not being used. I also took the opportunity to address an issue with the windows launcher script turning off `echo`. Instead it now avoids output using the `@` prefix for each command in the script.
> 
> I've tested that the scripts work (using `jextract --help`) on both Linux and Windows.

Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:

  set permissions during build

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/241/files
  - new: https://git.openjdk.org/jextract/pull/241/files/712670c3..89b8e2bd

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=241&range=02
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=241&range=01-02

  Stats: 9 lines in 2 files changed: 8 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jextract/pull/241.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/241/head:pull/241

PR: https://git.openjdk.org/jextract/pull/241

From jvernee at openjdk.org  Tue Apr 30 17:09:31 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 30 Apr 2024 17:09:31 GMT
Subject: RFR: 7903720: Change layout of jextract image [v4]
In-Reply-To: <FmvCKWrTOm4Y2WBZj6L-5Q5jEf8ioceekySRvJP0BBA=.5e24425f-b1d9-4cf9-9957-0aa98ab47b27@github.com>
References: <FmvCKWrTOm4Y2WBZj6L-5Q5jEf8ioceekySRvJP0BBA=.5e24425f-b1d9-4cf9-9957-0aa98ab47b27@github.com>
Message-ID: <zwD8bsUodb1bo8c9i60t0tV6GwaB5yDpp0aMqCQEZfY=.00886bc8-d218-4a77-a528-e897b3209a06@github.com>

> See JBS issue for problem description.
> 
> This patch changes the layout of the jextract image we produce. The new image has the 2 launcher scripts in the root of the image, with a nested `runtime` folder containing the jlink runtime image.
> 
> I've added both launcher scripts to the repo under the `src/main` directory, and they are copied to the image during the build. The script is somewhat simplified by removing a blank variable that was not being used. I also took the opportunity to address an issue with the windows launcher script turning off `echo`. Instead it now avoids output using the `@` prefix for each command in the script.
> 
> I've tested that the scripts work (using `jextract --help`) on both Linux and Windows.

Jorn Vernee has updated the pull request incrementally with four additional commits since the last revision:

 - set mac version to x64 pt2
 - set mac version to x64
 - only set file permissions if supported
 - pass JEXTRACT_JAVA_OPTIONS to launcher

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/241/files
  - new: https://git.openjdk.org/jextract/pull/241/files/89b8e2bd..a2768cfb

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=241&range=03
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=241&range=02-03

  Stats: 13 lines in 4 files changed: 2 ins; 0 del; 11 mod
  Patch: https://git.openjdk.org/jextract/pull/241.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/241/head:pull/241

PR: https://git.openjdk.org/jextract/pull/241

From jvernee at openjdk.org  Tue Apr 30 17:14:35 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 30 Apr 2024 17:14:35 GMT
Subject: RFR: 7903720: Change layout of jextract image [v5]
In-Reply-To: <FmvCKWrTOm4Y2WBZj6L-5Q5jEf8ioceekySRvJP0BBA=.5e24425f-b1d9-4cf9-9957-0aa98ab47b27@github.com>
References: <FmvCKWrTOm4Y2WBZj6L-5Q5jEf8ioceekySRvJP0BBA=.5e24425f-b1d9-4cf9-9957-0aa98ab47b27@github.com>
Message-ID: <80L3b8qn8O4Q4oxIouW1fIBtXV80eB9Hoa1oafIJ1M8=.a37edea1-5e0a-48ae-a8a7-6deab9f6dab0@github.com>

> See JBS issue for problem description.
> 
> This patch changes the layout of the jextract image we produce. The new image has the 2 launcher scripts in the root of the image, with a nested `runtime` folder containing the jlink runtime image.
> 
> I've added both launcher scripts to the repo under the `src/main` directory, and they are copied to the image during the build. The script is somewhat simplified by removing a blank variable that was not being used. I also took the opportunity to address an issue with the windows launcher script turning off `echo`. Instead it now avoids output using the `@` prefix for each command in the script.
> 
> I've tested that the scripts work (using `jextract --help`) on both Linux and Windows.

Jorn Vernee has updated the pull request incrementally with two additional commits since the last revision:

 - disable macos runs pt2
 - disable macos runs

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

Changes:
  - all: https://git.openjdk.org/jextract/pull/241/files
  - new: https://git.openjdk.org/jextract/pull/241/files/a2768cfb..3ccf4a7d

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jextract&pr=241&range=04
 - incr: https://webrevs.openjdk.org/?repo=jextract&pr=241&range=03-04

  Stats: 6 lines in 1 file changed: 0 ins; 5 del; 1 mod
  Patch: https://git.openjdk.org/jextract/pull/241.diff
  Fetch: git fetch https://git.openjdk.org/jextract.git pull/241/head:pull/241

PR: https://git.openjdk.org/jextract/pull/241

From jvernee at openjdk.org  Tue Apr 30 17:19:17 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 30 Apr 2024 17:19:17 GMT
Subject: RFR: 7903720: Change layout of jextract image [v5]
In-Reply-To: <80L3b8qn8O4Q4oxIouW1fIBtXV80eB9Hoa1oafIJ1M8=.a37edea1-5e0a-48ae-a8a7-6deab9f6dab0@github.com>
References: <FmvCKWrTOm4Y2WBZj6L-5Q5jEf8ioceekySRvJP0BBA=.5e24425f-b1d9-4cf9-9957-0aa98ab47b27@github.com>
 <80L3b8qn8O4Q4oxIouW1fIBtXV80eB9Hoa1oafIJ1M8=.a37edea1-5e0a-48ae-a8a7-6deab9f6dab0@github.com>
Message-ID: <P57du49HF_q2uCzAbHFsFgmfzcA0-uhS1U04e45d13I=.25b37288-831f-4ddd-8282-8b5ba242a4cf@github.com>

On Tue, 30 Apr 2024 17:14:35 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> See JBS issue for problem description.
>> 
>> This patch changes the layout of the jextract image we produce. The new image has the 2 launcher scripts in the root of the image, with a nested `runtime` folder containing the jlink runtime image.
>> 
>> I've added both launcher scripts to the repo under the `src/main` directory, and they are copied to the image during the build. The script is somewhat simplified by removing a blank variable that was not being used. I also took the opportunity to address an issue with the windows launcher script turning off `echo`. Instead it now avoids output using the `@` prefix for each command in the script.
>> 
>> I've tested that the scripts work (using `jextract --help`) on both Linux and Windows.
>
> Jorn Vernee has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - disable macos runs pt2
>  - disable macos runs

I've made a few more changes:

1. Implemented Maurizio's suggestion to allow passing options to the launcher through a shell variable
2. Set POSIX executable permissions for the copied script
3. Disable macos GHA runs. It looks like they switched their runner to arm64, so we can't use x64 llvm any more it seems.

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

PR Comment: https://git.openjdk.org/jextract/pull/241#issuecomment-2086075763

From mcimadamore at openjdk.org  Tue Apr 30 18:15:19 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Tue, 30 Apr 2024 18:15:19 GMT
Subject: RFR: 7903720: Change layout of jextract image [v5]
In-Reply-To: <80L3b8qn8O4Q4oxIouW1fIBtXV80eB9Hoa1oafIJ1M8=.a37edea1-5e0a-48ae-a8a7-6deab9f6dab0@github.com>
References: <FmvCKWrTOm4Y2WBZj6L-5Q5jEf8ioceekySRvJP0BBA=.5e24425f-b1d9-4cf9-9957-0aa98ab47b27@github.com>
 <80L3b8qn8O4Q4oxIouW1fIBtXV80eB9Hoa1oafIJ1M8=.a37edea1-5e0a-48ae-a8a7-6deab9f6dab0@github.com>
Message-ID: <r3RLek03xw8daUAt1Gnx4KmP8Uw9i4mGiCoMJUOJB4A=.b7716cdd-fb3e-4fb5-9fa2-842d26456e91@github.com>

On Tue, 30 Apr 2024 17:14:35 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> See JBS issue for problem description.
>> 
>> This patch changes the layout of the jextract image we produce. The new image has the 2 launcher scripts in the root of the image, with a nested `runtime` folder containing the jlink runtime image.
>> 
>> I've added both launcher scripts to the repo under the `src/main` directory, and they are copied to the image during the build. The script is somewhat simplified by removing a blank variable that was not being used. I also took the opportunity to address an issue with the windows launcher script turning off `echo`. Instead it now avoids output using the `@` prefix for each command in the script.
>> 
>> I've tested that the scripts work (using `jextract --help`) on both Linux and Windows.
>
> Jorn Vernee has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - disable macos runs pt2
>  - disable macos runs

Marked as reviewed by mcimadamore (Reviewer).

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

PR Review: https://git.openjdk.org/jextract/pull/241#pullrequestreview-2032144800

From jvernee at openjdk.org  Tue Apr 30 18:36:08 2024
From: jvernee at openjdk.org (Jorn Vernee)
Date: Tue, 30 Apr 2024 18:36:08 GMT
Subject: Integrated: 7903720: Change layout of jextract image
In-Reply-To: <FmvCKWrTOm4Y2WBZj6L-5Q5jEf8ioceekySRvJP0BBA=.5e24425f-b1d9-4cf9-9957-0aa98ab47b27@github.com>
References: <FmvCKWrTOm4Y2WBZj6L-5Q5jEf8ioceekySRvJP0BBA=.5e24425f-b1d9-4cf9-9957-0aa98ab47b27@github.com>
Message-ID: <NvFHUAgfbHv_XiMhgPAPaNfOHR0f60e4_qXPVj27jX0=.f8f10900-3ef3-4356-b319-c02d96e5d71d@github.com>

On Tue, 30 Apr 2024 14:49:25 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> See JBS issue for problem description.
> 
> This patch changes the layout of the jextract image we produce. The new image has the 2 launcher scripts in the root of the image, with a nested `runtime` folder containing the jlink runtime image.
> 
> I've added both launcher scripts to the repo under the `src/main` directory, and they are copied to the image during the build. The script is somewhat simplified by removing a blank variable that was not being used. I also took the opportunity to address an issue with the windows launcher script turning off `echo`. Instead it now avoids output using the `@` prefix for each command in the script.
> 
> I've tested that the scripts work (using `jextract --help`) on both Linux and Windows.

This pull request has now been integrated.

Changeset: b4da3284
Author:    Jorn Vernee <jvernee at openjdk.org>
URL:       https://git.openjdk.org/jextract/commit/b4da3284d41863af47d4a36b5829849b27cd47f4
Stats:     36 lines in 5 files changed: 22 ins; 6 del; 8 mod

7903720: Change layout of jextract image

Reviewed-by: mcimadamore

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

PR: https://git.openjdk.org/jextract/pull/241