[foreign-jextract] RFR: Update the README with Panama specific information, and information about the repo

[Maurizio Cimadamore]

On Fri, 13 Mar 2020 14:07:21 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Hi,
> 
> This patch updates the README file on the foreign-jextract branch, since that is features prominently on GitHub.
> 
> It also renames the file to README.md, so that GitHub picks up the right formatting.

Looks good, some comments and suggestions inline.

README.md line 1:

> 1:
> 2: Welcome to the JDK!

In general, I'd prefer to replace `repo` with `repository`; I'd also prefer to use a less informal approach (e.g.
instead of "you can build the repo", "the repo can be built")

README.md line 17:

> 16: ===================
> 17: This is a repo of OpenJDK Project Panama: Interconnecting JVM and native code. You can find more information at:
> https://openjdk.java.net/projects/panama/ 18:

This repository contains changes which aims at improving the interoperability between the Java programming language and
native libraries, which one of the main goals of Project Panama. More information can be found at:
https://openjdk.java.net/projects/panama/

README.md line 19:

> 18:
> 19: You can find the Project Panama JBS dashboard at: https://bugs.openjdk.java.net/Dashboard.jspa?selectPageId=18412
> 20:

The Project Panama JBS dashboard can be found at

README.md line 21:

> 20:
> 21: You can find early access (EA) snapshots at: http://jdk.java.net/panama/
> 22:

Early acccess (EA) binary snapshot can be found at:

README.md line 28:

> 27: - **foreign-abi**: Contains the developement of the foreign function interface (FFI), which can be used to call
> native code in a  .dll/.so/.dylib, or to create a native function pointer to a Java method which can be passed to code
> in a native library. 28: - **foreign-jextract**: Contains the developement of the jextract API, which can be used to
> create an abstract syntax tree from a C header file. There's also the accompanying jextract tool, which is a wrapper
> for the API and can be used to generate a Java interface to call the C library described by a given header file. 29:

Contains the development of an API to parse native headers, which can be used to create an abstract representation
(declarations) from a C header file. This branch also provides an accompanying extraction tool (jextract), which is
built on top of the API, and can be used to generate *Java bindings* to access functions and/or structs in a native
library described by a given header file.

README.md line 34:

> 33: ===================
> 34: Jextract requires [LLVM 9.x](https://releases.llvm.org/download.html) as a dependency. So, if you want to build the
> foreign-jextract branch yourself you will need to pass `--with-libclang=/path/to/llvm/root` when generating a build
> configuration. Please see
> [doc/building.md](https://github.com/openjdk/panama-foreign/blob/foreign-jextract/doc/building.md) for general building
> instructions.

So, to build the foreign-jextract branch, the flag `--with-libclang=/path/to/llvm/root` must be supplied when
generating a build configuration.

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

PR: https://git.openjdk.java.net/panama-foreign/pull/51