3 Organisation of the source code
This is where the sources of R live. The main folders to know about in
This is the location for the header files containing the declarations and definitions of the R API. Some of these are publicly available in packages:
src/include/Rinternals.h. Main declarations of the R API.
SEXPTYPEenum; array accessors like
REAL(), various object accessors like
ENCLOS(); functions like
Rf_coerceVector(); shortcuts to global objects like
src/include/Rinlinedfuns.h. Part of the R API that is exported with definitions, so they can be inlined in client code.
PROTECT()macro expands to),
Some files are only available if you’re developing R:
src/include/Defn.h. Declarations for the private accessors, data structures, and functions. This includes declarations for the functions prefixed in
do_, which contain the native code of primitive R functions.
FUNTABdata structure for the array of primitive functions
RCNTXTthe data structure for the context frames of the call stack; etc.
This folder contains the sources of R. As an interpreted language, R follows the read-eval-print-loop pattern. We briefely present the files implementing each of these four components.
src/main/gram.yis the input file for the bison parser generator. It implements the R parser, i.e. the “read” part of the REPL. You’ll find the operator precedence table, the grammar of the R language, and the low level constructors for the objects of the parse tree (function calls mostly).
The parser can read entire files (most commonly from
source()), or it can read a single string, e.g. the user input at the console. It returns an
EXPRSXPvector containing each top-level expression.
src/main/eval.cimplements the interpreter of R code the “eval” part of the REPL. The main function
eval()evaluates the components of an expression, until it can return a value. This is a recursive process, for instance calling a function causes the arguments to be stored in promises and then
eval()is called again with the body of the function.
The logic for function calls (promising arguments, creating a new context on the call stack, evaluating the body) is implemented in this file.
src/main/print.ccontains the “print” code that is invoked on implicit printing of top-level expression results, as well as explicit printing via the R
print()function. The printing routine is recursive because data structures are recursive: if you print a list, each element is printed in turn via a recursive call. Printing S3 and S4 objects causes a callback to R so that
show()methods can be invoked.
src/main/main.c. This is where the main “loop” of the REPL is implemented. This involves the code for initialising R, waiting for user inputs, and dealing with parse errors or expression results (catching top-level jumps, saving
Other important files are:
src/main/names.cdefines the primitive function table (such as
eval()). This table contains information about the primitive functions: a function pointer for the native routine (prefixed with
do_and declared in Defn.h), whether the primitive function is internal or exposed to the user, whether it evaluates its arguments and returns its value invisibly. For primitives implementing binary operators like
+, the table also contains precedence information used for deparsing.
src/main/context.cimplements the R call stack.
src/main/errors.cimplements condition handling and error jumps.
src/main/objects.cimplements method dispatch for S3 and S4 objects.
3.1.3 Other folders of interest
src/scriptsfolder contains shell scripts for
R CMDcommands. For instance,
R CMD checkis implemented in
src/scripts/check. The scripts are often very simple and invoke R code implemented in the tools package.
src/libraryfolder contains the sources of the base packages, like
The unit tests for R are stored in the
tests folder. This folder contains:
READMEfile describing all the
makeshortcuts for running various subsets of the tests.
General purpose regression test files like
tests/reg-tests-1d.R. Add new tests to the file with the highest letter (1d at the time of writing). The files suffixed with lower letters are for older versions of R.
.Rout.savefiles containing the console output after running the test files.
.Rout.savefiles for the examples of base packages.