[External] : Re: Javadoc for API

[Nir Lisker]

>
> Note that --dump-includes already exists, and generates a flat list of
> `--include-XXX` options that can be passed back to jextract (not JSON).


I saw that, but these are just string names. They don't contain all the
info in a Declaration, which can be useful to the user.

And it still adds extra steps. When jextract receives a head, it generates
a list of Declarations. Now, instead of directly sending it back, it maps
them to strings (in whatever format) and writes them to a file; then an
application needs to read that file and parse the strings back to
Declarations. But we already had these Declarations to begin with.
The way I see it, jextract has 2 functions: inspect a header(s), and
generate bindings for a header(s). While ToolProvier#run covers these, it
requires extra hoops to jump through, such as the above parsing and also
reading messages from the standard streams. Removing the exception  on a
parsing error was enough to disable one of the features of the app that
informs the user that an include dir is missing.

If you're interested, I can give you and anyone else in the jextract team
access to the repo and you can try it out, although it's still in beta. I
intend to make it public anyway when I can prove it works on non-Windows
machines.

On Thu, Jan 30, 2025 at 8:20 PM Jorn Vernee <jorn.vernee at oracle.com> wrote:

> Note that --dump-includes already exists, and generates a flat list of
> `--include-XXX` options that can be passed back to jextract (not JSON). You
> would need to parse these options manually. I think the format would be
> relatively stable, only needing to change if we change the command line
> options.
>
> > Speaking of 'parse', I notice that it doesn't throw an exception on a
> missing '#include <header.h>' as it used to. Now I only see a printed
> error. Has this changed? Is there a way to capture this error somehow so
> that the user knows something went wrong?
>
> Yes, this changed as part of: https://github.com/openjdk/jextract/pull/255
>
> It looks like the Logger class that was added is not part of the public
> API, so right now I don't think there's a way to capture those errors aside
> from capturing and parsing them from the output.
>
> Jorn
> On 30-1-2025 14:06, Nir Lisker wrote:
>
> It's probably possible to do, but looks roundabout.
>
> Here is my setup in more detail:
> 1. A header is given to the application. It calls 'parse' on it to get all
> the Declarations.
> 2. The user can configure which declarations to include in the GUI, and
> also the other options such as class name, macros, output dir etc.
> 3. The 'run' method is called with the arguments generated from the
> configuration.
>
> It's all in-memory.
>
> With --dump-includes:
> 1. A header is given to the application. A JSON file is created.
> 2. The file is read and parsed to produce the Declarations. Configuring a
> JSON parser is already a lot of work for polymorphic sybtyping (all the
> types of Declarations). Will jextract provide a parser? What is the format?
> Is it stable?
> 3. Is 2 above.
> 4. Is 3 above.
>
> So we complicated things by creating a file from which we need to read the
> data that would otherwise be given to us directly by 'parse'. At least this
> is my understanding.
>
> Speaking of 'parse', I notice that it doesn't throw an exception on a
> missing '#include <header.h>' as it used to. Now I only see a printed
> error. Has this changed? Is there a way to capture this error somehow so
> that the user knows something went wrong?
>
> On Tue, Jan 28, 2025 at 5:06 PM Jorn Vernee <jorn.vernee at oracle.com>
> wrote:
>
>> > There is no need for a dump.
>>
>> But, do you think you could do the things you're doing, using
>> JextractTool::parse, by using --dump-includes instead?
>>
>> I'm trying to assess if we even need the API at all, or if we can just
>> have the ToolProvider.
>>
>> Jorn
>> On 28-1-2025 15:12, Nir Lisker wrote:
>>
>> I use
>> JextractTool.parse(List<String> arg0, String... arg1)
>> to inspect given header files. Then I use
>> ToolProvider.run(PrintStream out, PrintStream err, String... args)
>> which is not Jextract-specific to run the tool with the user's
>> configuration. There is no need for a dump.
>>
>> I want to release an alpha soon so you'll be able to see how it works.
>>
>> On Tue, Jan 28, 2025 at 2:28 PM Jorn Vernee <jorn.vernee at oracle.com>
>> wrote:
>>
>>> Hey Nir,
>>>
>>> The jextract API has been neglected for a while (as you've found).
>>> Initially it was a way of avoiding adding many flags to jextract, to do
>>> things like filtering, renaming, and other things. The idea being that
>>> if users wanted more control of what jextract did, they could use the
>>> API. But, now it seems like we're moving in that direction any way, with
>>> the JSON based configuration:
>>> https://bugs.openjdk.org/browse/CODETOOLS-7903788
>>>
>>> I think we need to re-asses which use cases the jextract API addresses,
>>> and whether using jextract through the ToolProvider interface, with the
>>> extended configuration options, is also an option.
>>>
>>> IIRC your use case is filtering the jextract output, right? Do you think
>>> it would be possible to use the ToolProvider interface with a
>>> combination of --dump-includes, and automatically generated
>>> --include-XXX flags, to achieve the same level of functionality?
>>>
>>> Jorn
>>>
>>> On 26-1-2025 08:51, Nir Lisker wrote:
>>> > Hi,
>>> >
>>> > There are several public methods the JextractTool exposes. Please
>>> > javadoc to these methods so tool users will know what they do and how
>>> > to use them.
>>> >
>>> > Thanks,
>>> > - Nir
>>>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jextract-dev/attachments/20250130/476fcfdc/attachment-0001.htm>