move more README files into documentation, add fledgling section on project structure

com.oracle.truffle.r.native/gnur/README

-This is a multi-step process to build GnuR in such a way that FASTR can use some of the libraries.
-After building GnuR we extract configuration information for use in building packages in the FastR environment.
-This goes into the file platform.mk, which is included in the Makefile's for the standard packages built for FastR.
-The main change is to define the symbol FASTR to ensure that some important modifications to Rinternals.h are made
-(e.g. changing an SEXP to a JNI jobject).
-

com.oracle.truffle.r.native/include/README

-The header files that are included when compiling the code of native packages in the FastR environment.
-
-The starting position is that these files are identical to those in GnuR and that the FastR implementation
-differences are entirely encapsulated in the method implementations in the fficall library. It is TBD whether
-this can be completely transparent but,if not, the goal would be for minimal changes to the standard header files.

com.oracle.truffle.r.native/library/README

-This directory tree contains the default packages for FastR. Each package directory contains a '.gz' file that was
-created from the corresponding GnuR 'library' directory, plus necessary C source and header files, most notably 'init.c',
-also copied from GnuR. Since these files reference functions in the GnuR implementation, 'init.c' is recompiled
-in the FastR environment and the resulting '.so' replaces the one from the '.gz' file in the FastR 'library' directory.
-Absolutely minimal changes are made to the C source, typically just to define (as empty functions), rather than reference,
-the C functions that are passed to R_registerRoutines. This step is still necesssary in FastR as it causes R symbols that are'
-referenced in the R package code to become defined.
-
-Note that 'datasets' and 'fastr' don't actually have any native code, but it is convenient to store them here. Note also that
-'fastr', obviously, does not originate from GnuR, so its build process is completely different.
-
-Given that we only support MacOS/Linux, it is expedient to just store the tar'ed content of the GnuR library directories
-for those targets as 'source' files in the distribution. In time, when FastR can create packages directly, the build will
-change to work that way.

documentation/dev/Index.md

@@ -2,7 +2,9 @@
 
 ## Index
 
-[R FFI Implementation](ffi.md)
+* [Project Structure](structure.md)
+* [Building](building.md)
+* [R FFI Implementation](ffi.md)
 
 
 

documentation/dev/building.md

+# Introduction
+
+This section contains more information regarding the build process. The `mx build` command will build both the Java projects and the native projects.
+
+# Details on Building the Native Code
+
+## Building GNU R
+
+The `com.oracle.truffle.r.native/gnur` directory contains the `Makefile` for building GNU R in such a way that
+parts are reusable by FastR. The GNU R source code is download by
+
+It is a multi-step process to build GNU R in such a way that FASTR can use some of the libraries.
+After building GNU R we extract configuration information for use in building packages in the FastR environment.
+This goes into the file `platform.mk`, which is included in the `Makefile``s for the standard packages built for FastR.
+The main change is to define the symbol `FASTR` to ensure that some important modifications to `Rinternals.h` are made
+(e.g. changing a `SEXP` to a `void*`).
+
+## Building the Standard GNU R Packages
+
+This directory tree contains the default packages for FastR. Most packages contain native (C/Fortran) code that
+must be recompiled for FastR to ensure that the FFI calls are handled correctly. The regenerated `package.so` file overwrites
+the file in the `library/package/libs` directory; otherwise the directory contents are identical to GNU R.
+
+As far as possible the native recompilation reference the corresponding source files in the `com.oracle.truffle.r.native/gnur`
+directory. In a few case these files have to be modified but every attempt it made to avoid wholesale copy of GNU R source files.
+
+Note that `datasets` doesn`t actually have any native code, but it is convenient to store it here to mirror GNU R.

documentation/dev/structure.md

+# Introduction
+
+The FastR codebase is structured around IDE `projects`, which are contained in directories beginning with `com.oracle.truffle.r`.
+The expectation is that source code will be viewed and edited in an IDE (we will use Eclipse as the example) and the `mx` tool
+has support for automatically generating the IDE project metadata via the `ideinit` command. N.B. if you run this before you have built the system with `mx build`
+do not be surprised that it will compile some Java classes. It does this to gather information about Java annotation processors that is necessary for
+correct rebuilding within the IDE.
+
+The majority of the projects are "Java" projects, but any project with `native` in its name contains native code, e.g. C code, and is (ultimately) built
+using `make`. `mx` handles this transparently. Note, however, that editing and building the native code in an IDE requires support for C development to have
+been installed. E.g. for Eclipse, the CDE plugin.