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

[Jorn Vernee]

On Fri, 13 Mar 2020 14:40:05 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.
>
> Jorn Vernee has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Fixing some typos
>  - Review comments

Fixing some typos

README.md line 17:

> 16: ===================
> 17: 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/ 18:

Suggestion:

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

README.md line 21:

> 20:
> 21: Early acccess (EA) binary snapshot can be found at: http://jdk.java.net/panama/
> 22:

Suggestion:

Early acccess (EA) binary snapshots can be found at: http://jdk.java.net/panama/

README.md line 26:

> 25: This repository houses three main branches:
> 26: - **foreign-memaccess**: Contains the developement of the foreign memory access API for [JEP
> 370](https://openjdk.java.net/jeps/370), which can be used to interact with different kinds of memory resource,
> inluding so-called off-heap or native memory. 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.

Suggestion:

- **foreign-memaccess**: Contains the developement of the foreign memory access API for [JEP
    370](https://openjdk.java.net/jeps/370), which can be used to interact with different kinds of memory resources,
    including so-called off-heap or native memory.

README.md line 27:

> 26: - **foreign-memaccess**: Contains the developement of the foreign memory access API for [JEP
> 370](https://openjdk.java.net/jeps/370), which can be used to interact with different kinds of memory resource,
> inluding so-called off-heap or native memory. 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 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.

Suggestion:

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

README.md line 30:

> 29:
> 30: The foreign-jextract branch depends on the foreign-abi branch, which in turn depends on the foreign-memaccess
> branch. As such, the foreign-jextract is the most complete of the three and therefore the default branch of this
> repositorysitory. 31:

Suggestion:

The foreign-jextract branch depends on the foreign-abi branch, which in turn depends on the foreign-memaccess branch.
As such, the foreign-jextract branch is the most complete of the three and therefore the default branch of this
repository.

README.md line 34:

> 33: ===================
> 34: Jextract requires [LLVM 9.x](https://releases.llvm.org/download.html) as a dependency. So, to build the
> foreign-jextract branch, the flag --with-libclang=/path/to/llvm/root must be supplied 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.

Suggestion:

Jextract requires [LLVM 9.x](https://releases.llvm.org/download.html) as a dependency. So, to build the
foreign-jextract branch, the flag `--with-libclang=/path/to/llvm/root` must be supplied 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.

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

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