Namespace for inner classes in jextract

[Duncan Gittins]

On 10/03/2021 13:12, Maurizio Cimadamore wrote:
>
> On 10/03/2021 12:43, Duncan Gittins wrote:
>>
>> If/when jextract supports --symbols includefile to filter by name 
>> then it could also incorporate syntax to specify aliases to resolve a 
>> name clash, eg "pvalueA=MYpvalueA"
>>
> True - at the same time this is exactly the kind of things that made 
> us gravitate towards the idea of plugins and APIs - e.g. once you 
> start pulling on this string there are many "features" that people 
> would want to see attached to the "filtering" mechanism:
>
> * give custom names to extracted symbols
> * give custom _types_ to extracted symbol (e.g. String instead of 
> MemoryAddress, or long -> long long, which is sometimes very helpful 
> to achieve cross-platform compatibility)
> * map different headers to different packages (according to some 
> specified mapping)
> * custom getter/setter/accessor names
> * filter set of accessors for struct fields (e.g. read-only structs?)
> * add custom javadoc to extracted symbols
> * add custom pre-amble/post-amble to extracted functions (e.g. to make 
> sure that passed segments are not closed while the function is executed)
> * specify which functions should have Java -> native state transition 
> omitted (e.g. "trivial" functions, in the ForeignLinker API lingo)
> * import function-like macros with given explicit signature
> * ...
>
> At which point we're well past the point of "filtering".

> Don't get me wrong - these are all reasonable things to do (and to 
> ask) - but you see the tension here: it's simply not possible to 
> enforce all the above with command line options (the previous jextract 
> incarnation tried to add some of those, but failed). An API is the 
> "right" level to deal with many of these - but there is, I believe, a 
> genuine discomfort with the idea of having to write a jextract plugin 
> for something that, on paper, seems intuitive enough.
>
Understood - yes there are many features to deal with and many people to 
please!

I think the first non-incubator release of jextract should work "out of 
the box" with only the bare minimum of command line options provided to 
enable the simplest level of filtering. Nothing more, so that the bulk 
of first time jextract users won't need to deal with extensions or 
bespoke JextractTool build.

For most in-house applications and sensible libraries the "--filter" 
flag does the job.  However it would be a shame if the JDK JExtract Tool 
Guide also needs a section describing the need for "del / rm" to tidy up 
the generated code for a subsequent production release [and this is what 
the various tech web sites would highlight as required to get a sensible 
code base size afterwards].

> I keep coming back to the idea of some configuration file (which could 
> initially pre-populated by jextract itself). While working with config 
> files is not as pleasant or expressive as working with code (as 
> everything gets compressed down to some kind of serialized form), it 
> seems to me one of the few practical way to get there.
>
Agree and Jextract already supports a config file right now:

     jextract @myconfig

This works sufficiently well for a first release and follows the pattern 
of other JDK tools like jpackage (so handles # comments, blank lines, 
multiple @files, can be checked in etc).

In my view all that is missing is command line options for multiple 
"--sym symbol_to_keep" to a pick name to keep in the generation process, 
and "--writeconfig myconfig.new" to write current run options to file 
(for editing / split / re-submit) => a neat formatted list of all params 
used by jextract PLUS list of all symbols in the run.

The symbols section could be in alphabetic order grouped under 
"#header_xyz.h" plus all "--sym XYZ" in that run followed then by 
"#header_xyz.h" plus "# -sym xyz" for all filtered items. Thus a 
developer can tweak the settings / add more --filter header.xyz for bulk 
excludes, or amend individual symbols before the next jextract run.

Splitting the symbols section to a separate file allows easy switch 
between development and production mode jextract builds:

     jextract @myconfig                           # for prototypes / 
early development
     jextract @myconfig @mysymbols  # for test cycles / prod release

Duncan

> An alternative could be to adopt an approach similar to javac 
> annotation processors, where jextract could accept a classfile 
> specifying some "symbol filter implementation". This implementation 
> will be called by jextract before each new symbol is generated, so 
> that the client will have the last say over how things will be laid 
> out (and this could be done interacting with some kind of API).
>
> Maurizio
>
>
>