Section “Creating R Packages” in Writing R Extensions
Total Page:16
File Type:pdf, Size:1020Kb
Writing R Extensions Version 3.1.0 Under development (2013-03-29) R Core Team Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the con- ditions 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 lan- guage, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the R Core Team. Copyright c 1999{2013 R Core Team i Table of Contents Acknowledgements ::::::::::::::::::::::::::::::::: 1 1 Creating R packages:::::::::::::::::::::::::::: 2 1.1 Package structure :::::::::::::::::::::::::::::::::::::::::::::: 3 1.1.1 The `DESCRIPTION' file :::::::::::::::::::::::::::::::::::: 4 1.1.2 Licensing:::::::::::::::::::::::::::::::::::::::::::::::::: 9 1.1.3 The `INDEX' file :::::::::::::::::::::::::::::::::::::::::: 10 1.1.4 Package subdirectories:::::::::::::::::::::::::::::::::::: 11 1.1.5 Data in packages ::::::::::::::::::::::::::::::::::::::::: 14 1.1.6 Non-R scripts in packages :::::::::::::::::::::::::::::::: 15 1.2 Configure and cleanup :::::::::::::::::::::::::::::::::::::::: 16 1.2.1 Using `Makevars'::::::::::::::::::::::::::::::::::::::::: 19 1.2.1.1 OpenMP support:::::::::::::::::::::::::::::::::::: 22 1.2.1.2 Using pthreads :::::::::::::::::::::::::::::::::::::: 23 1.2.1.3 Compiling in sub-directories ::::::::::::::::::::::::: 23 1.2.2 Configure example ::::::::::::::::::::::::::::::::::::::: 24 1.2.3 Using F95 code :::::::::::::::::::::::::::::::::::::::::: 26 1.3 Checking and building packages ::::::::::::::::::::::::::::::: 26 1.3.1 Checking packages ::::::::::::::::::::::::::::::::::::::: 27 1.3.2 Building package tarballs ::::::::::::::::::::::::::::::::: 30 1.3.3 Building binary packages ::::::::::::::::::::::::::::::::: 32 1.4 Writing package vignettes ::::::::::::::::::::::::::::::::::::: 33 1.4.1 Encodings and vignettes:::::::::::::::::::::::::::::::::: 35 1.4.2 Non-Sweave vignettes :::::::::::::::::::::::::::::::::::: 35 1.5 Submitting a package to CRAN :::::::::::::::::::::::::::::::: 36 1.6 Package namespaces::::::::::::::::::::::::::::::::::::::::::: 36 1.6.1 Specifying imports and exports ::::::::::::::::::::::::::: 37 1.6.2 Registering S3 methods :::::::::::::::::::::::::::::::::: 38 1.6.3 Load hooks :::::::::::::::::::::::::::::::::::::::::::::: 38 1.6.4 useDynLib ::::::::::::::::::::::::::::::::::::::::::::::: 39 1.6.5 An example :::::::::::::::::::::::::::::::::::::::::::::: 41 1.6.6 Namespaces with S4 classes and methods ::::::::::::::::: 42 1.7 Writing portable packages ::::::::::::::::::::::::::::::::::::: 43 1.7.1 PDF size ::::::::::::::::::::::::::::::::::::::::::::::::: 46 1.7.2 Check timing::::::::::::::::::::::::::::::::::::::::::::: 46 1.7.3 Encoding issues :::::::::::::::::::::::::::::::::::::::::: 47 1.7.4 Binary distribution ::::::::::::::::::::::::::::::::::::::: 48 1.8 Diagnostic messages::::::::::::::::::::::::::::::::::::::::::: 48 1.9 Internationalization ::::::::::::::::::::::::::::::::::::::::::: 50 1.9.1 C-level messages ::::::::::::::::::::::::::::::::::::::::: 50 1.9.2 R messages::::::::::::::::::::::::::::::::::::::::::::::: 50 1.9.3 Preparing translations :::::::::::::::::::::::::::::::::::: 51 1.10 CITATION files:::::::::::::::::::::::::::::::::::::::::::::: 51 ii 1.11 Package types:::::::::::::::::::::::::::::::::::::::::::::::: 52 1.11.1 Frontend :::::::::::::::::::::::::::::::::::::::::::::::: 52 1.12 Services:::::::::::::::::::::::::::::::::::::::::::::::::::::: 53 2 Writing R documentation files ::::::::::::::: 54 2.1 Rd format :::::::::::::::::::::::::::::::::::::::::::::::::::: 54 2.1.1 Documenting functions ::::::::::::::::::::::::::::::::::: 55 2.1.2 Documenting data sets ::::::::::::::::::::::::::::::::::: 60 2.1.3 Documenting S4 classes and methods ::::::::::::::::::::: 61 2.1.4 Documenting packages ::::::::::::::::::::::::::::::::::: 61 2.2 Sectioning :::::::::::::::::::::::::::::::::::::::::::::::::::: 62 2.3 Marking text:::::::::::::::::::::::::::::::::::::::::::::::::: 62 2.4 Lists and tables ::::::::::::::::::::::::::::::::::::::::::::::: 64 2.5 Cross-references ::::::::::::::::::::::::::::::::::::::::::::::: 65 2.6 Mathematics :::::::::::::::::::::::::::::::::::::::::::::::::: 66 2.7 Figures ::::::::::::::::::::::::::::::::::::::::::::::::::::::: 66 2.8 Insertions ::::::::::::::::::::::::::::::::::::::::::::::::::::: 67 2.9 Indices :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 68 2.10 Platform-specific documentation ::::::::::::::::::::::::::::: 68 2.11 Conditional text ::::::::::::::::::::::::::::::::::::::::::::: 68 2.12 Dynamic pages :::::::::::::::::::::::::::::::::::::::::::::: 69 2.13 User-defined macros:::::::::::::::::::::::::::::::::::::::::: 70 2.14 Encoding :::::::::::::::::::::::::::::::::::::::::::::::::::: 71 2.15 Processing documentation files ::::::::::::::::::::::::::::::: 71 2.16 Editing Rd files :::::::::::::::::::::::::::::::::::::::::::::: 72 3 Tidying and profiling R code ::::::::::::::::: 73 3.1 Tidying R code ::::::::::::::::::::::::::::::::::::::::::::::: 73 3.2 Profiling R code for speed ::::::::::::::::::::::::::::::::::::: 73 3.3 Profiling R code for memory use::::::::::::::::::::::::::::::: 75 3.3.1 Memory statistics from Rprof :::::::::::::::::::::::::::: 76 3.3.2 Tracking memory allocations ::::::::::::::::::::::::::::: 76 3.3.3 Tracing copies of an object ::::::::::::::::::::::::::::::: 76 3.4 Profiling compiled code ::::::::::::::::::::::::::::::::::::::: 77 3.4.1 Linux :::::::::::::::::::::::::::::::::::::::::::::::::::: 77 3.4.1.1 sprof :::::::::::::::::::::::::::::::::::::::::::::::: 77 3.4.1.2 oprofile:::::::::::::::::::::::::::::::::::::::::::::: 78 3.4.2 Solaris ::::::::::::::::::::::::::::::::::::::::::::::::::: 79 3.4.3 OS X :::::::::::::::::::::::::::::::::::::::::::::::::::: 79 iii 4 Debugging ::::::::::::::::::::::::::::::::::::: 80 4.1 Browsing ::::::::::::::::::::::::::::::::::::::::::::::::::::: 80 4.2 Debugging R code :::::::::::::::::::::::::::::::::::::::::::: 81 4.3 Using gctorture and valgrind :::::::::::::::::::::::::::::::::: 85 4.3.1 Using gctorture :::::::::::::::::::::::::::::::::::::::::: 85 4.3.2 Using valgrind ::::::::::::::::::::::::::::::::::::::::::: 86 4.4 Debugging compiled code ::::::::::::::::::::::::::::::::::::: 88 4.4.1 Finding entry points in dynamically loaded code :::::::::: 89 4.4.2 Inspecting R objects when debugging ::::::::::::::::::::: 89 5 System and foreign language interfaces:::::: 92 5.1 Operating system access :::::::::::::::::::::::::::::::::::::: 92 5.2 Interface functions .C and .Fortran::::::::::::::::::::::::::: 92 5.3 dyn.load and dyn.unload :::::::::::::::::::::::::::::::::::: 94 5.4 Registering native routines :::::::::::::::::::::::::::::::::::: 96 5.4.1 Speed considerations ::::::::::::::::::::::::::::::::::::: 98 5.4.2 Linking to native routines in other packages :::::::::::::: 99 5.5 Creating shared objects :::::::::::::::::::::::::::::::::::::: 100 5.6 Interfacing C++ code :::::::::::::::::::::::::::::::::::::::: 101 5.7 Fortran I/O:::::::::::::::::::::::::::::::::::::::::::::::::: 103 5.8 Linking to other packages :::::::::::::::::::::::::::::::::::: 103 5.8.1 Unix-alikes:::::::::::::::::::::::::::::::::::::::::::::: 103 5.8.2 Windows:::::::::::::::::::::::::::::::::::::::::::::::: 104 5.9 Handling R objects in C ::::::::::::::::::::::::::::::::::::: 105 5.9.1 Handling the effects of garbage collection :::::::::::::::: 106 5.9.2 Allocating storage::::::::::::::::::::::::::::::::::::::: 108 5.9.3 Details of R types ::::::::::::::::::::::::::::::::::::::: 108 5.9.4 Attributes :::::::::::::::::::::::::::::::::::::::::::::: 110 5.9.5 Classes:::::::::::::::::::::::::::::::::::::::::::::::::: 112 5.9.6 Handling lists ::::::::::::::::::::::::::::::::::::::::::: 112 5.9.7 Handling character data::::::::::::::::::::::::::::::::: 113 5.9.8 Finding and setting variables :::::::::::::::::::::::::::: 113 5.9.9 Some convenience functions ::::::::::::::::::::::::::::: 114 5.9.9.1 Semi-internal convenience functions::::::::::::::::: 114 5.9.10 Named objects and copying :::::::::::::::::::::::::::: 115 5.10 Interface functions .Call and .External:::::::::::::::::::: 116 5.10.1 Calling .Call :::::::::::::::::::::::::::::::::::::::::: 116 5.10.2 Calling .External ::::::::::::::::::::::::::::::::::::: 117 5.10.3 Missing and special values:::::::::::::::::::::::::::::: 119 5.11 Evaluating R expressions from C :::::::::::::::::::::::::::: 119 5.11.1 Zero-finding:::::::::::::::::::::::::::::::::::::::::::: 121 5.11.2 Calculating numerical derivatives::::::::::::::::::::::: 122 5.12 Parsing R code from C:::::::::::::::::::::::::::::::::::::: 125 5.12.1 Accessing source references ::::::::::::::::::::::::::::: 126 5.13 External pointers and weak references ::::::::::::::::::::::: 127 5.13.1 An example :::::::::::::::::::::::::::::::::::::::::::: 128 5.14 Vector accessor functions:::::::::::::::::::::::::::::::::::: 129 5.15 Character encoding issues ::::::::::::::::::::::::::::::::::: 129 iv 6 The R API: entry points for C code :::::::: 131 6.1 Memory allocation ::::::::::::::::::::::::::::::::::::::::::: 131 6.1.1 Transient storage allocation ::::::::::::::::::::::::::::: 132 6.1.2 User-controlled memory :::::::::::::::::::::::::::::::::