From 83798d2063fc939650cfd8aebc5ada3e675fad0e Mon Sep 17 00:00:00 2001 From: Mick Jordan <mick.jordan@oracle.com> Date: Thu, 15 Dec 2016 16:33:46 -0800 Subject: [PATCH] move more README files into documentation, add fledgling section on project structure --- com.oracle.truffle.r.native/gnur/README | 6 ----- com.oracle.truffle.r.native/include/README | 5 ---- com.oracle.truffle.r.native/library/README | 14 ----------- documentation/dev/Index.md | 4 +++- documentation/dev/building.md | 27 ++++++++++++++++++++++ documentation/dev/structure.md | 11 +++++++++ 6 files changed, 41 insertions(+), 26 deletions(-) delete mode 100644 com.oracle.truffle.r.native/gnur/README delete mode 100644 com.oracle.truffle.r.native/include/README delete mode 100644 com.oracle.truffle.r.native/library/README create mode 100644 documentation/dev/building.md create mode 100644 documentation/dev/structure.md diff --git a/com.oracle.truffle.r.native/gnur/README b/com.oracle.truffle.r.native/gnur/README deleted file mode 100644 index e241ed42ce..0000000000 --- a/com.oracle.truffle.r.native/gnur/README +++ /dev/null @@ -1,6 +0,0 @@ -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). - diff --git a/com.oracle.truffle.r.native/include/README b/com.oracle.truffle.r.native/include/README deleted file mode 100644 index 86972bd087..0000000000 --- a/com.oracle.truffle.r.native/include/README +++ /dev/null @@ -1,5 +0,0 @@ -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. diff --git a/com.oracle.truffle.r.native/library/README b/com.oracle.truffle.r.native/library/README deleted file mode 100644 index 3b933fbd7d..0000000000 --- a/com.oracle.truffle.r.native/library/README +++ /dev/null @@ -1,14 +0,0 @@ -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. diff --git a/documentation/dev/Index.md b/documentation/dev/Index.md index f663e8b80c..3a1d4565e6 100644 --- a/documentation/dev/Index.md +++ b/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) diff --git a/documentation/dev/building.md b/documentation/dev/building.md new file mode 100644 index 0000000000..7dc6f48402 --- /dev/null +++ b/documentation/dev/building.md @@ -0,0 +1,27 @@ +# 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. diff --git a/documentation/dev/structure.md b/documentation/dev/structure.md new file mode 100644 index 0000000000..14851e3135 --- /dev/null +++ b/documentation/dev/structure.md @@ -0,0 +1,11 @@ +# 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. -- GitLab