Writing R Extensions Version 2.1.0 (2005-04-18) R Development Core Team Permission is granted to make and distribute verbatim copies of this manual provided the copy- right notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the condi- tions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the R Development Core Team. Copyright c 1999–2005 R Development Core Team ISBN 3-900051-11-9 i Table of Contents Acknowledgements ........................................ 1 1 Creating R packages .................................... 2 1.1 Package structure ............................................................. 2 1.1.1 The ‘DESCRIPTION’ file .................................................... 2 1.1.2 The ‘INDEX’ file ........................................................... 4 1.1.3 The ‘install.R’ and ‘R_PROFILE.R’ files ................................... 5 1.1.4 Package subdirectories .................................................... 5 1.1.5 Package bundles .......................................................... 7 1.2 Configure and cleanup ......................................................... 7 1.2.1 Using ‘Makevars’ ......................................................... 9 1.2.2 Configure example ....................................................... 10 1.3 Checking and building packages ............................................... 12 1.3.1 Checking packages ....................................................... 12 1.3.2 Building packages ........................................................ 13 1.3.3 Customizing checking and building ........................................ 14 1.4 Writing package vignettes ..................................................... 14 1.5 Submitting a package to CRAN ................................................ 15 1.6 Package name spaces ......................................................... 16 1.6.1 Specifying imports and exports ........................................... 16 1.6.2 Registering S3 methods .................................................. 17 1.6.3 Load hooks.............................................................. 17 1.6.4 An example ............................................................. 17 1.6.5 Summary – converting an existing package ................................. 18 1.6.6 Name spaces with formal classes and methods.............................. 18 1.7 Writing portable packages..................................................... 19 1.8 Diagnostic messages .......................................................... 20 1.9 Localization.................................................................. 21 1.9.1 C-level messages ......................................................... 21 1.9.2 R messages .............................................................. 22 1.10 Package types ............................................................... 22 1.10.1 Frontend ............................................................... 22 1.10.2 Translation............................................................. 22 2 Writing R documentation files ......................... 24 2.1 Rd format ................................................................... 24 2.1.1 Documenting functions ................................................... 24 2.1.2 Documenting data sets ................................................... 27 2.1.3 Documenting S4 classes and methods...................................... 28 2.2 Sectioning ................................................................... 29 2.3 Marking text................................................................. 29 2.4 Lists and tables .............................................................. 30 2.5 Cross-references .............................................................. 31 2.6 Mathematics ................................................................. 31 2.7 Insertions .................................................................... 32 2.8 Indices ...................................................................... 32 2.9 Platform-specific documentation ............................................... 32 ii 2.10 Encoding ................................................................... 33 2.11 Processing Rd format ........................................................ 33 3 Tidying and profiling R code........................... 34 3.1 Tidying R code .............................................................. 34 3.2 Profiling R code .............................................................. 34 4 System and foreign language interfaces ................. 37 4.1 Operating system access ...................................................... 37 4.2 Interface functions .C and .Fortran ........................................... 37 4.3 dyn.load and dyn.unload .................................................... 39 4.4 Registering native routines .................................................... 40 4.5 Creating shared objects ....................................................... 41 4.6 Interfacing C++ code.......................................................... 42 4.7 Handling R objects in C ...................................................... 43 4.7.1 Handling the effects of garbage collection .................................. 45 4.7.2 Allocating storage ....................................................... 46 4.7.3 Details of R types........................................................ 46 4.7.4 Attributes ............................................................... 47 4.7.5 Classes.................................................................. 49 4.7.6 Handling lists............................................................ 49 4.7.7 Finding and setting variables ............................................. 50 4.7.8 Named objects and copying............................................... 51 4.8 Interface functions .Call and .External....................................... 52 4.8.1 Calling .Call ........................................................... 52 4.8.2 Calling .External ....................................................... 53 4.8.3 Missing and special values ................................................ 54 4.9 Evaluating R expressions from C .............................................. 55 4.9.1 Zero-finding ............................................................. 57 4.9.2 Calculating numerical derivatives ......................................... 58 4.10 Parsing R code from C ...................................................... 61 4.11 Debugging compiled code .................................................... 61 4.11.1 Finding entry points in dynamically loaded code .......................... 61 4.11.2 Inspecting R objects when debugging..................................... 62 5 The R API: entry points for C code .................... 64 5.1 Memory allocation ........................................................... 64 5.1.1 Transient storage allocation............................................... 64 5.1.2 User-controlled memory .................................................. 65 5.2 Error handling ............................................................... 65 5.2.1 Error handling from FORTRAN .......................................... 65 5.3 Random number generation ................................................... 66 5.4 Missing and IEEE special values ............................................... 66 5.5 Printing ..................................................................... 66 5.5.1 Printing from FORTRAN ................................................ 67 5.6 Calling C from FORTRAN and vice versa ...................................... 67 5.7 Numerical analysis subroutines ................................................ 68 5.7.1 Distribution functions .................................................... 68 5.7.2 Mathematical functions .................................................. 69 5.7.3 Numerical Utilities ....................................................... 69 5.7.4 Mathematical constants .................................................. 71 5.8 Optimization................................................................. 71 5.9 Integration................................................................... 72 iii 5.10 Utility functions............................................................. 73 5.11 Internationalization.......................................................... 75 5.12 Allowing interrupts .......................................................... 75 5.13 Platform and version information ............................................. 75 5.14 Inlining C functions ......................................................... 76 5.15 Using these functions in your own C code ..................................... 76 5.16 Organization of header files .................................................. 77 6 Generic functions and methods ........................ 78 6.1 Adding new generics .......................................................... 79 7 Linking GUIs and other front-ends to R ................ 80 7.1 Embedding R under Unix-alikes ..............................................