Writing R Extensions
Total Page：16
File Type：pdf, Size：1020Kb
Writing R Extensions Version 4.1.1 Patched (2021-09-22) R Core Team This manual is for R, version 4.1.1 Patched (2021-09-22). Copyright c 1999{2021 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 conditions 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 an- other language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the 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 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 8 1.1.3 Package Dependencies::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 9 1.1.3.1 Suggested packages:::::::::::::::::::::::::::::::::::::::::::::::::::::: 12 1.1.4 The INDEX file ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 13 1.1.5 Package subdirectories ::::::::::::::::::::::::::::::::::::::::::::::::::::::: 13 1.1.6 Data in packages::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 16 1.1.7 Non-R scripts in packages :::::::::::::::::::::::::::::::::::::::::::::::::::: 18 1.1.8 Specifying URLs ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 19 1.2 Configure and cleanup :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 19 1.2.1 Using Makevars:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 23 1.2.1.1 OpenMP support ::::::::::::::::::::::::::::::::::::::::::::::::::::::: 26 1.2.1.2 Using pthreads :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 28 1.2.1.3 Compiling in sub-directories ::::::::::::::::::::::::::::::::::::::::::::: 29 1.2.2 Configure example ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 30 1.2.3 Using F9x code :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 31 1.2.4 Using C++ code ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 32 1.3 Checking and building packages ::::::::::::::::::::::::::::::::::::::::::::::::::: 34 1.3.1 Checking packages ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 34 1.3.2 Building package tarballs::::::::::::::::::::::::::::::::::::::::::::::::::::: 38 1.3.3 Building binary packages ::::::::::::::::::::::::::::::::::::::::::::::::::::: 39 1.4 Writing package vignettes ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 40 1.4.1 Encodings and vignettes ::::::::::::::::::::::::::::::::::::::::::::::::::::: 42 1.4.2 Non-Sweave vignettes :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 42 1.5 Package namespaces :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 43 1.5.1 Specifying imports and exports::::::::::::::::::::::::::::::::::::::::::::::: 44 1.5.2 Registering S3 methods :::::::::::::::::::::::::::::::::::::::::::::::::::::: 45 1.5.3 Load hooks :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 45 1.5.4 useDynLib ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 46 1.5.5 An example:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 48 1.5.6 Namespaces with S4 classes and methods ::::::::::::::::::::::::::::::::::::: 48 1.6 Writing portable packages::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 50 1.6.1 PDF size :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 59 1.6.2 Check timing :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 59 1.6.3 Encoding issues :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 60 1.6.4 Portable C and C++ code ::::::::::::::::::::::::::::::::::::::::::::::::::: 61 1.6.4.1 Common symbols ::::::::::::::::::::::::::::::::::::::::::::::::::::::: 66 1.6.5 Binary distribution :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 66 1.7 Diagnostic messages :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 67 1.8 Internationalization ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 68 1.8.1 C-level messages ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 68 1.8.2 R messages :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 69 1.8.3 Preparing translations ::::::::::::::::::::::::::::::::::::::::::::::::::::::: 69 1.9 CITATION files :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 69 ii 1.10 Package types ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 70 1.10.1 Frontend ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 70 1.11 Services ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 71 2 Writing R documentation files ::::::::::::::::::::::::::::::: 72 2.1 Rd format :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 72 2.1.1 Documenting functions::::::::::::::::::::::::::::::::::::::::::::::::::::::: 73 2.1.2 Documenting data sets ::::::::::::::::::::::::::::::::::::::::::::::::::::::: 77 2.1.3 Documenting S4 classes and methods::::::::::::::::::::::::::::::::::::::::: 78 2.1.4 Documenting packages ::::::::::::::::::::::::::::::::::::::::::::::::::::::: 79 2.2 Sectioning :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 79 2.3 Marking text ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 80 2.4 Lists and tables::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 82 2.5 Cross-references::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 82 2.6 Mathematics:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 83 2.7 Figures ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 83 2.8 Insertions::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 84 2.9 Indices ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 85 2.10 Platform-specific documentation ::::::::::::::::::::::::::::::::::::::::::::::::: 85 2.11 Conditional text ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 85 2.12 Dynamic pages :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 86 2.13 User-defined macros ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 87 2.14 Encoding :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 88 2.15 Processing documentation files ::::::::::::::::::::::::::::::::::::::::::::::::::: 88 2.16 Editing Rd files:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 89 3 Tidying and profiling R code :::::::::::::::::::::::::::::::: 90 3.1 Tidying R code ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 90 3.2 Profiling R code for speed::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 90 3.3 Profiling R code for memory use :::::::::::::::::::::::::::::::::::::::::::::::::: 92 3.3.1 Memory statistics from Rprof :::::::::::::::::::::::::::::::::::::::::::::::: 92 3.3.2 Tracking memory allocations ::::::::::::::::::::::::::::::::::::::::::::::::: 93 3.3.3 Tracing copies of an object ::::::::::::::::::::::::::::::::::::::::::::::::::: 93 3.4 Profiling compiled code ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 93 3.4.1 Linux :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 94 3.4.1.1 sprof :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 94 3.4.1.2 oprofile and operf ::::::::::::::::::::::::::::::::::::::::::::::::::::::: 94 3.4.2 Solaris ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 97 3.4.3 macOS :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 97 4 Debugging ::::::::::::::::::::::::::::::::::::::::::::::::::::: 98 4.1 Browsing ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 98 4.2 Debugging R code :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 99 4.3 Checking memory access ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 102 4.3.1 Using gctorture ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 103 4.3.2 Using valgrind :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 103 4.3.3 Using the Address Sanitizer ::::::::::::::::::::::::::::::::::::::::::::::::: 105 4.3.3.1 Using the Leak Sanitizer ::::::::::::::::::::::::::::::::::::::::::::::: 106 4.3.4 Using the Undefined Behaviour Sanitizer :::::::::::::::::::::::::::::::::::: 107 4.3.5 Other analyses with `clang' ::::::::::::::::::::::::::::::::::::::::::::::::: 108 4.3.6 Other analyses with `gcc' ::::::::::::::::::::::::::::::::::::::::::::::::::: 108 4.3.7 Using `Dr. Memory' :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 108 4.3.8 Fortran array bounds checking :::::::::::::::::::::::::::::::::::::::::::::: 108 iii 4.4 Debugging compiled code :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 109 4.4.1 Finding entry points in dynamically loaded code :::::::::::::::::::::::::::: 110 4.4.2 Inspecting R objects when debugging ::::::::::::::::::::::::::::::::::::::: 111 4.4.3 Debugging on macOS :::::::::::::::::::::::::::::::::::::::::::::::::::::::