RFR: 7903128: Overhaul jextract README [v2]

[Jorn Vernee]

On Thu, 24 Mar 2022 13:15:44 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> I've improved the README file, by putting the expanding the build section, and putting it more front and center.
>> I have also streamlined the remaining contents a little, and removed the parts that were describing the foreign API (not really needed here).
>
> Maurizio Cimadamore has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Simplify dir tree structure
>  - More fixes

Very nice!

Minor nits inline

README.md line 3:

> 1: ## Jextract
> 2: 
> 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 to a given native library, and the generated Java bindings builds upon the [Foreign Function & Memory API](https://openjdk.java.net/jeps/419). 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/)).

Suggestion:

`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/419). 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/)).

README.md line 7:

> 5: ### Getting started
> 6: 
> 7: `jextract` depends on the [C libclang API](https://clang.llvm.org/doxygen/group__CINDEX.html). To build the jextract sources, the easiest option is to download LLVM binaries for your platform, which can be found [here](https://releases.llvm.org/download.html). Both the `jextract` tool and the bindings it generates depend heavily on the [Foreign Function & Memory API](https://openjdk.java.net/jeps/419), so a suitable [jdk 18 distribution](https://jdk.java.net/18/) is also required.

I think this should say something about which version of LLVM should be used, and is expected to work.
Suggestion:

`jextract` depends on the [C libclang API](https://clang.llvm.org/doxygen/group__CINDEX.html). To build the jextract sources, the easiest option is to download LLVM binaries for your platform, which can be found [here](https://releases.llvm.org/download.html). Any version from 9 and up should work. Both the `jextract` tool and the bindings it generates depend heavily on the [Foreign Function & Memory API](https://openjdk.java.net/jeps/419), so a suitable [jdk 18 distribution](https://jdk.java.net/18/) is also required.

README.md line 33:

> 31: 
> 32: ```sh
> 33: build/jextract/bin/jextract 

for me the exe is under `build/jextract/jextract.exe` is this different on Linux?

README.md line 115:

> 113: #### Filtering symbols
> 114: 
> 115: The `jextract` tool includes several customization options. Users can select what in which package the generated code should be emitted, and what the name of the main extracted class should be. To allow for symbol filtering, `jextract` can generate a *dump* of all the symbols encountered in an header file; this dump can be manipulated, and then used as an argument file (using the `@argfile` syntax also available in other JDK tools) to e.g. generate bindings only for a *subset* of symbols seen by `jextract`. For instance, if we run `jextract` with as follows:

Suggestion:

The `jextract` tool includes several customization options. Users can select in which package the generated code should be emitted, and what the name of the main extracted class should be. To allow for symbol filtering, `jextract` can generate a *dump* of all the symbols encountered in an header file; this dump can be manipulated, and then used as an argument file (using the `@argfile` syntax also available in other JDK tools) to e.g. generate bindings only for a *subset* of symbols seen by `jextract`. For instance, if we run `jextract` with as follows:

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

Marked as reviewed by jvernee (no project role).

PR: https://git.openjdk.java.net/jextract/pull/3