From fb16a8fa0ed26d17b2de81b2eea15e836917c1ca Mon Sep 17 00:00:00 2001 From: andrie Date: Sun, 15 Oct 2023 00:17:21 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20@=20rstudio/?= =?UTF-8?q?r-manuals@c75dd7962caab3caebfab9b3543c220ac0c24b72=20?= =?UTF-8?q?=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- r-admin/Installing-R-under-Unix-alikes.html | 2 +- r-admin/search.json | 2 +- r-exts/Creating-R-packages.html | 2 +- r-exts/The-R-API.html | 6 +-- r-exts/search.json | 4 +- r-ints/Function-and-variable-index.html | 50 +++++++++++++-------- r-ints/Tools.html | 36 +++++++++------ r-ints/search.json | 4 +- 8 files changed, 63 insertions(+), 43 deletions(-) diff --git a/r-admin/Installing-R-under-Unix-alikes.html b/r-admin/Installing-R-under-Unix-alikes.html index 9cbca31..94a9c7c 100644 --- a/r-admin/Installing-R-under-Unix-alikes.html +++ b/r-admin/Installing-R-under-Unix-alikes.html @@ -607,7 +607,7 @@

<

2.7.4 C standards

-

Compiling R requires C99 or later: C11 and C17 are minor updates, but the substantial update planned for ‘C23’ (now expected in 2024) will also be supported.

+

Compiling R requires C99 or later: C11 and C17 are minor updates, but the substantial update planned for ‘C23’ (now expected ca April 2024) will also be supported.

As from R 4.3.0 there is support for packages to indicate their preferred C version. Macros CC17, C17FLAGS, CC23 and C23FLAGS can be set in config.site (there are examples there). Those for C17 should support C17 or earlier and not allow C23 additions so for example bool, true and false can be used as identifiers. Those for C23 should support new types such as bool.

Some compilers warn enthusiastically about prototypes. For most, omitting -Wstrict-prototypes in C17FLAGS suffices. However, versions 15 and later of LLVM clang and 14.0.3 and later of Apple clang warn by default in all modes if -Wall or -pedantic is used, and may need -Wno-strict-prototypes.

diff --git a/r-admin/search.json b/r-admin/search.json index d180bc0..1efeb69 100644 --- a/r-admin/search.json +++ b/r-admin/search.json @@ -67,7 +67,7 @@ "href": "Installing-R-under-Unix-alikes.html#other-options", "title": "2  Installing R under Unix-alikes", "section": "2.7 Other Options", - "text": "2.7 Other Options\nThere are many other installation options, most of which are listed by configure --help. Almost all of those not listed elsewhere in this manual are either standard autoconf options not relevant to R or intended for specialist uses by the R developers.\nOne that may be useful when working on R itself is the option --disable-byte-compiled-packages, which ensures that the base and recommended packages are not byte-compiled. (Alternatively the (make or environment) variable R_NO_BASE_COMPILE can be set to a non-empty value for the duration of the build.)\nOption --with-internal-tzcode makes use of R’s own code and copy of the IANA database for managing timezones. This will be preferred where there are issues with the system implementation, usually involving times after 2037 or before 1916. An alternative time-zone directory8 can be used, pointed to by environment variable TZDIR: this should contain files such as Europe/London. On all tested OSes the system timezone was deduced correctly, but if necessary it can be set as the value of environment variable TZ.8 How to prepare such a directory is described in file src/extra/tzone/Notes in the R sources.\nOptions --with-internal-iswxxxxx, --with-internal-towlower and --with-internal-wcwidth were introduced in R 4.1.0. These control the replacement of the system wide-character classification (such as iswprint), case-changing (wctrans) and width (wcwidth and wcswidth) functions by ones contained in the R sources. Replacement of the classification functions has been done for many years on macOS and AIX (and Windows): option --with-internal-iswxxxxx allows this to be suppressed on those platforms or used on others. Replacing the case-changing functions was new in R 4.1.0 and the default on macOS (and on Windows since R 4.2.0). Replacement of the width functions has also been done for many years and remains the default. These options will only matter to those working with non-ASCII character data, especially in languages written in a non-Western script9 (which includes ‘symbols’ such as emoji). Note that one of those iswxxxxx is iswprint which is used to decide whether to output a character as a glyph or as a \\U{xxxxxx} escape—for example, try \"\\U1f600\", an emoji. The width functions are of most importance in East Asian locale: their values differ between such locales. (Replacing the system functions provides a degree of platform-independence (including to OS updates) but replaces it with a dependence on the R version.)9 But on Windows problems have been seen with case-changing functions on accented Latin-1 characters.\n\n2.7.1 Debugging Symbols\nBy default, configure adds a flag (usually -g) to the compilation flags for C, Fortran and CXX sources. This will slow down compilation and increase object sizes of both R and packages, so it may be a good idea to change those flags (set CFLAGS etc in config.site before configuring, or edit files Makeconf and etc/Makeconf between running configure and make).\nHaving debugging symbols available is useful both when running R under a debugger (e.g., R -d gdb) and when using sanitizers and valgrind, all things intended for experts.\nDebugging symbols (and some others) can be ‘stripped’ on installation by using\nmake install-strip\nHow well this is supported depends on the platform: it works best on those using GNU binutils. On x86_64 Linux a typical reduction in overall size was from 92MB to 66MB. On macOS debugging symbols are not by default included in .dylib and .so files, so there is negligible difference.\n\n\n2.7.2 OpenMP Support\nBy default configure searches for suitable flags10 for OpenMP support for the C, C++ (default standard) and Fortran compilers.10 for example, -fopenmp, -fiopenmp, -xopenmp or -qopenmp. This includes for clang and the Intel and Oracle compilers.\nOnly the C result is currently used for R itself, and only if MAIN_LD/DYLIB_LD were not specified. This can be overridden by specifying\nR_OPENMP_CFLAGS\nUse for packages has similar restrictions (involving SHLIB_LD and similar: note that as Fortran code is by default linked by the C (or C++) compiler, both need to support OpenMP) and can be overridden by specifying some of\nSHLIB_OPENMP_CFLAGS\nSHLIB_OPENMP_CXXFLAGS\nSHLIB_OPENMP_FFLAGS\nSetting these to an empty value will disable OpenMP for that compiler (and configuring with --disable-openmp will disable all detection11 of OpenMP). The configure detection test is to compile and link a standalone OpenMP program, which is not the same as compiling a shared object and loading it into the C program of R’s executable. Note that overridden values are not tested.11 This does not necessarily disable use of OpenMP – the configure code allows for platforms where OpenMP is used without a flag. For the flang compiler in late 2017, the Fortran runtime always used OpenMP.\n\n\n2.7.3 C++ Support\nC++ is not used by R itself, but support is provided for installing packages with C++ code via make macros defined in file etc/Makeconf (and with explanations in file config.site):\nCXX\nCXXFLAGS\nCXXPICFLAGS\nCXXSTD\n\nCXX11\nCXX11STD\nCXX11FLAGS\nCXX11PICFLAGS\n\nCXX14\nCXX14STD\nCXX14FLAGS\nCXX14PICFLAGS\n\nCXX17\nCXX17STD\nCXX17FLAGS\nCXX17PICFLAGS\n\nCXX20\nCXX20STD\nCXX20FLAGS\nCXX20PICFLAGS\n\nCXX23\nCXX23STD\nCXX23FLAGS\nCXX23PICFLAGS\nThe macros CXX etc are those used by default for C++ code. configure will attempt to set the rest suitably, choosing for CXXSTD and CXX11STD a suitable flag such as -std=c++11 for C++11 support (which is required if C++ is to be supported at all). inferred values can be overridden in file config.site or on the configure command line: user-supplied values will be tested by compiling some C++11/14/17/20/23 code.\nIt may be that there is no suitable flag for C++14/17/20/23 support with the default compiler, in which case a different compiler could be selected for CXX14/CXX17/CXX20/CXX23 with its corresponding flags.\nThe -std flag is supported by the GCC, clang++ and Intel compilers. Currently accepted values are (plus some synonyms)\ng++: c++11 gnu+11 c++14 gnu++14 c++17 gnu++17 c++2a gnu++2a (from 8)\n c++20 gnu++20 (from 10) c++23 gnu++23 c++2b gnu++2b (from 11)\nIntel: c++11 gnu+11 c++14 gnu++14 c++17 gnu++17\n c++20 gnu++20 (from 2021.1) c++2b gnu++2b (from 2022.2)\n(Those for LLVM clang++ are documented at https://clang.llvm.org/cxx_status.html, and follow g++: -std=c++20 is supported from Clang 10, -std=c++2b from Clang 13. Apple Clang supports -std=c++2b from 13.1.6.)\n‘Standards’ for g++ starting with gnu enable ‘GNU extensions’: what those are is hard to track down.\nFor the use of C++11 and later in R packages see the ‘Writing R Extensions’ manual. Prior to R 3.6.0 the default C++ standard was that of the compiler used: currently it is C++17 (if available): this can be overridden by setting CXXSTD when R is configured.\nhttps://en.cppreference.com/w/cpp/compiler_support indicates which versions of common compilers support (parts of) which C++ standards. GCC 5 was the minimum version with sufficient C++14 support. GCC introduced C++17 support gradually, but version 7 should suffice.\n\n\n2.7.4 C standards\nCompiling R requires C99 or later: C11 and C17 are minor updates, but the substantial update planned for ‘C23’ (now expected in 2024) will also be supported.\nAs from R 4.3.0 there is support for packages to indicate their preferred C version. Macros CC17, C17FLAGS, CC23 and C23FLAGS can be set in config.site (there are examples there). Those for C17 should support C17 or earlier and not allow C23 additions so for example bool, true and false can be used as identifiers. Those for C23 should support new types such as bool.\nSome compilers warn enthusiastically about prototypes. For most, omitting -Wstrict-prototypes in C17FLAGS suffices. However, versions 15 and later of LLVM clang and 14.0.3 and later of Apple clang warn by default in all modes if -Wall or -pedantic is used, and may need -Wno-strict-prototypes.\n\n\n2.7.5 Link-Time Optimization\nThere is support for using link-time optimization (LTO) if the toolchain supports it: configure with flag --enable-lto. When LTO is enabled it is used for compiled code in add-on packages unless the flag --enable-lto=R is used12.12 Then recommended packages installed as part of the R installation do use LTO, but not packages installed later.\nThe main benefit seen to date from LTO has been detecting long-standing bugs in the ways packages pass arguments to compiled code and between compilation units. Benchmarking in 2020 with gcc/gfortran 10 showed gains of a few percent in increased performance and reduction in installed size for builds without debug symbols, but large size reductions for some packages13 with debug symbols. (Performance and size gains are said to be most often seen in complex C++ builds.)13 A complete CRAN installation reduced from 50 to 35GB.\nWhether toolchains support LTO is often unclear: all of the C compiler, the Fortran compiler14 and linker have to support it, and support it by the same mechanism (so mixing compiler families may not work and a non-default linker may be needed). It has been supported by the GCC and LLVM projects for some years with diverging implementations.14 although there is the possibility to exclude Fortran but that misses some of the benefits.\nLTO support was added in 2011 for GCC 4.5 on Linux but was little used before 2019: compiler support has steadily improved over those years and --enable-lto=R is nowadays used for some routine CRAN checking.\nUnfortunately --enable-lto may be accepted but silently do nothing useful if some of the toolchain does not support LTO: this is less common than it once was.\nVarious macros can be set in file config.site to customize how LTO is used. If the Fortran compiler is not of the same family as the C/C++ compilers, set macro LTO_FC (probably to empty). Macro LTO_LD can be used to select an alternative linker should that be needed.\n\n\n2.7.6 LTO with GCC\nThis has been tested on Linux with gcc/gfortran 8 and later: that needed setting (e.g. in config.site)\nAR=gcc-ar\nRANLIB=gcc-ranlib\nFor non-system compilers or if those wrappers have not been installed one may need something like\nAR=\"ar --plugin=/path/to/liblto_plugin.so\"\nRANLIB=\"ranlib --plugin=/path/to/liblto_plugin.so\"\namd NM may be needed to be set analogously. (If using an LTO-enabled build to check packages, set environment variable UserNM15 to gcc-nm.)15 not NM as we found make overriding that.\nWith GCC 5 and later it is possible to parallelize parts of the LTO linking process: set the make macro LTO to something like LTO=-flto=8 (to use 8 threads), for example in file config.site.\nUnder some circumstances and for a few packages, the PIC flags have needed overriding on Linux with GCC 9 and later: e.g use in config.site:\nCPICFLAGS=-fPIC\nCXXPICFLAGS=-fPIC\nCXX11PICFLAGS=-fPIC\nCXX14PICFLAGS=-fPIC\nCXX17PICFLAGS=-fPIC\nCXX20PICFLAGS=-fPIC\nFPICFLAGS=-fPIC\nWe suggest only using these if the problem is encountered (it was not seen on CRAN with GCC 10 at the time of writing).\nNote that R may need to be re-compiled after even a minor update to the compiler (e.g. from 10.1 to 10.2) but this may not be clear from confused compiler messages.\n\n\n2.7.7 LTO with LLVM\nLLVM supports another type of LTO called ‘Thin LTO’ as well as a similar implementation to GCC, sometimes called ‘Full LTO’. (See https://clang.llvm.org/docs/ThinLTO.html.) Currently the LLVM compilers relevant to R are clang and flang for which this can be selected by setting macro LTO=-flto=thin. LLVM has\nAR=llvm-ar\nRANLIB=llvm-ranlib\n(but macOS does not, and these are not needed there). Where the linker supports a parallel backend for Thin LTO this can be specified via the macro LTO_LD: see the URL above for per-linker settings and further linking optimizations.)\nFor example, on macOS one might use\nLTO=-flto=thin\nLTO_FC=\nLTO_LD=-Wl,-mllvm,-threads=4\nto use Thin LTO with 4 threads for C/C++ code, but skip LTO for Fortran code compiled with gfortran.\nIt is said to be particularly beneficial to use -O3 for clang in conjunction with LTO.\nIt seems that flang may support LTO, but with no documentation as yet.\nThe 2020s versions of Intel’s C/C++ compilers are based on LLVM and as such support LLVM-style LTO, both ‘full’ and ‘thin’. This might use something like\nLTO=-flto=thin -flto-jobs=8\n\n\n2.7.8 LTO for package checking\nLTO effectively compiles all the source code in a package as a single compilation unit and so allows the compiler (with sufficient diagnostic flags such as -Wall) to check consistency between what are normally separate compilation units.\nWith gcc/gfortran 9.x and later16 LTO will flag inconsistencies in calls to Fortran subroutines/functions, both between Fortran source files and between Fortran and C/C++. gfortran 8.4, 9.2 and later can help understanding these by extracting C prototypes from Fortran source files with option -fc-prototypes-external, e.g. that (at the time of writing) Fortran LOGICAL corresponds to int_least32_t * in C.16 probably also 8.4 and later." + "text": "2.7 Other Options\nThere are many other installation options, most of which are listed by configure --help. Almost all of those not listed elsewhere in this manual are either standard autoconf options not relevant to R or intended for specialist uses by the R developers.\nOne that may be useful when working on R itself is the option --disable-byte-compiled-packages, which ensures that the base and recommended packages are not byte-compiled. (Alternatively the (make or environment) variable R_NO_BASE_COMPILE can be set to a non-empty value for the duration of the build.)\nOption --with-internal-tzcode makes use of R’s own code and copy of the IANA database for managing timezones. This will be preferred where there are issues with the system implementation, usually involving times after 2037 or before 1916. An alternative time-zone directory8 can be used, pointed to by environment variable TZDIR: this should contain files such as Europe/London. On all tested OSes the system timezone was deduced correctly, but if necessary it can be set as the value of environment variable TZ.8 How to prepare such a directory is described in file src/extra/tzone/Notes in the R sources.\nOptions --with-internal-iswxxxxx, --with-internal-towlower and --with-internal-wcwidth were introduced in R 4.1.0. These control the replacement of the system wide-character classification (such as iswprint), case-changing (wctrans) and width (wcwidth and wcswidth) functions by ones contained in the R sources. Replacement of the classification functions has been done for many years on macOS and AIX (and Windows): option --with-internal-iswxxxxx allows this to be suppressed on those platforms or used on others. Replacing the case-changing functions was new in R 4.1.0 and the default on macOS (and on Windows since R 4.2.0). Replacement of the width functions has also been done for many years and remains the default. These options will only matter to those working with non-ASCII character data, especially in languages written in a non-Western script9 (which includes ‘symbols’ such as emoji). Note that one of those iswxxxxx is iswprint which is used to decide whether to output a character as a glyph or as a \\U{xxxxxx} escape—for example, try \"\\U1f600\", an emoji. The width functions are of most importance in East Asian locale: their values differ between such locales. (Replacing the system functions provides a degree of platform-independence (including to OS updates) but replaces it with a dependence on the R version.)9 But on Windows problems have been seen with case-changing functions on accented Latin-1 characters.\n\n2.7.1 Debugging Symbols\nBy default, configure adds a flag (usually -g) to the compilation flags for C, Fortran and CXX sources. This will slow down compilation and increase object sizes of both R and packages, so it may be a good idea to change those flags (set CFLAGS etc in config.site before configuring, or edit files Makeconf and etc/Makeconf between running configure and make).\nHaving debugging symbols available is useful both when running R under a debugger (e.g., R -d gdb) and when using sanitizers and valgrind, all things intended for experts.\nDebugging symbols (and some others) can be ‘stripped’ on installation by using\nmake install-strip\nHow well this is supported depends on the platform: it works best on those using GNU binutils. On x86_64 Linux a typical reduction in overall size was from 92MB to 66MB. On macOS debugging symbols are not by default included in .dylib and .so files, so there is negligible difference.\n\n\n2.7.2 OpenMP Support\nBy default configure searches for suitable flags10 for OpenMP support for the C, C++ (default standard) and Fortran compilers.10 for example, -fopenmp, -fiopenmp, -xopenmp or -qopenmp. This includes for clang and the Intel and Oracle compilers.\nOnly the C result is currently used for R itself, and only if MAIN_LD/DYLIB_LD were not specified. This can be overridden by specifying\nR_OPENMP_CFLAGS\nUse for packages has similar restrictions (involving SHLIB_LD and similar: note that as Fortran code is by default linked by the C (or C++) compiler, both need to support OpenMP) and can be overridden by specifying some of\nSHLIB_OPENMP_CFLAGS\nSHLIB_OPENMP_CXXFLAGS\nSHLIB_OPENMP_FFLAGS\nSetting these to an empty value will disable OpenMP for that compiler (and configuring with --disable-openmp will disable all detection11 of OpenMP). The configure detection test is to compile and link a standalone OpenMP program, which is not the same as compiling a shared object and loading it into the C program of R’s executable. Note that overridden values are not tested.11 This does not necessarily disable use of OpenMP – the configure code allows for platforms where OpenMP is used without a flag. For the flang compiler in late 2017, the Fortran runtime always used OpenMP.\n\n\n2.7.3 C++ Support\nC++ is not used by R itself, but support is provided for installing packages with C++ code via make macros defined in file etc/Makeconf (and with explanations in file config.site):\nCXX\nCXXFLAGS\nCXXPICFLAGS\nCXXSTD\n\nCXX11\nCXX11STD\nCXX11FLAGS\nCXX11PICFLAGS\n\nCXX14\nCXX14STD\nCXX14FLAGS\nCXX14PICFLAGS\n\nCXX17\nCXX17STD\nCXX17FLAGS\nCXX17PICFLAGS\n\nCXX20\nCXX20STD\nCXX20FLAGS\nCXX20PICFLAGS\n\nCXX23\nCXX23STD\nCXX23FLAGS\nCXX23PICFLAGS\nThe macros CXX etc are those used by default for C++ code. configure will attempt to set the rest suitably, choosing for CXXSTD and CXX11STD a suitable flag such as -std=c++11 for C++11 support (which is required if C++ is to be supported at all). inferred values can be overridden in file config.site or on the configure command line: user-supplied values will be tested by compiling some C++11/14/17/20/23 code.\nIt may be that there is no suitable flag for C++14/17/20/23 support with the default compiler, in which case a different compiler could be selected for CXX14/CXX17/CXX20/CXX23 with its corresponding flags.\nThe -std flag is supported by the GCC, clang++ and Intel compilers. Currently accepted values are (plus some synonyms)\ng++: c++11 gnu+11 c++14 gnu++14 c++17 gnu++17 c++2a gnu++2a (from 8)\n c++20 gnu++20 (from 10) c++23 gnu++23 c++2b gnu++2b (from 11)\nIntel: c++11 gnu+11 c++14 gnu++14 c++17 gnu++17\n c++20 gnu++20 (from 2021.1) c++2b gnu++2b (from 2022.2)\n(Those for LLVM clang++ are documented at https://clang.llvm.org/cxx_status.html, and follow g++: -std=c++20 is supported from Clang 10, -std=c++2b from Clang 13. Apple Clang supports -std=c++2b from 13.1.6.)\n‘Standards’ for g++ starting with gnu enable ‘GNU extensions’: what those are is hard to track down.\nFor the use of C++11 and later in R packages see the ‘Writing R Extensions’ manual. Prior to R 3.6.0 the default C++ standard was that of the compiler used: currently it is C++17 (if available): this can be overridden by setting CXXSTD when R is configured.\nhttps://en.cppreference.com/w/cpp/compiler_support indicates which versions of common compilers support (parts of) which C++ standards. GCC 5 was the minimum version with sufficient C++14 support. GCC introduced C++17 support gradually, but version 7 should suffice.\n\n\n2.7.4 C standards\nCompiling R requires C99 or later: C11 and C17 are minor updates, but the substantial update planned for ‘C23’ (now expected ca April 2024) will also be supported.\nAs from R 4.3.0 there is support for packages to indicate their preferred C version. Macros CC17, C17FLAGS, CC23 and C23FLAGS can be set in config.site (there are examples there). Those for C17 should support C17 or earlier and not allow C23 additions so for example bool, true and false can be used as identifiers. Those for C23 should support new types such as bool.\nSome compilers warn enthusiastically about prototypes. For most, omitting -Wstrict-prototypes in C17FLAGS suffices. However, versions 15 and later of LLVM clang and 14.0.3 and later of Apple clang warn by default in all modes if -Wall or -pedantic is used, and may need -Wno-strict-prototypes.\n\n\n2.7.5 Link-Time Optimization\nThere is support for using link-time optimization (LTO) if the toolchain supports it: configure with flag --enable-lto. When LTO is enabled it is used for compiled code in add-on packages unless the flag --enable-lto=R is used12.12 Then recommended packages installed as part of the R installation do use LTO, but not packages installed later.\nThe main benefit seen to date from LTO has been detecting long-standing bugs in the ways packages pass arguments to compiled code and between compilation units. Benchmarking in 2020 with gcc/gfortran 10 showed gains of a few percent in increased performance and reduction in installed size for builds without debug symbols, but large size reductions for some packages13 with debug symbols. (Performance and size gains are said to be most often seen in complex C++ builds.)13 A complete CRAN installation reduced from 50 to 35GB.\nWhether toolchains support LTO is often unclear: all of the C compiler, the Fortran compiler14 and linker have to support it, and support it by the same mechanism (so mixing compiler families may not work and a non-default linker may be needed). It has been supported by the GCC and LLVM projects for some years with diverging implementations.14 although there is the possibility to exclude Fortran but that misses some of the benefits.\nLTO support was added in 2011 for GCC 4.5 on Linux but was little used before 2019: compiler support has steadily improved over those years and --enable-lto=R is nowadays used for some routine CRAN checking.\nUnfortunately --enable-lto may be accepted but silently do nothing useful if some of the toolchain does not support LTO: this is less common than it once was.\nVarious macros can be set in file config.site to customize how LTO is used. If the Fortran compiler is not of the same family as the C/C++ compilers, set macro LTO_FC (probably to empty). Macro LTO_LD can be used to select an alternative linker should that be needed.\n\n\n2.7.6 LTO with GCC\nThis has been tested on Linux with gcc/gfortran 8 and later: that needed setting (e.g. in config.site)\nAR=gcc-ar\nRANLIB=gcc-ranlib\nFor non-system compilers or if those wrappers have not been installed one may need something like\nAR=\"ar --plugin=/path/to/liblto_plugin.so\"\nRANLIB=\"ranlib --plugin=/path/to/liblto_plugin.so\"\namd NM may be needed to be set analogously. (If using an LTO-enabled build to check packages, set environment variable UserNM15 to gcc-nm.)15 not NM as we found make overriding that.\nWith GCC 5 and later it is possible to parallelize parts of the LTO linking process: set the make macro LTO to something like LTO=-flto=8 (to use 8 threads), for example in file config.site.\nUnder some circumstances and for a few packages, the PIC flags have needed overriding on Linux with GCC 9 and later: e.g use in config.site:\nCPICFLAGS=-fPIC\nCXXPICFLAGS=-fPIC\nCXX11PICFLAGS=-fPIC\nCXX14PICFLAGS=-fPIC\nCXX17PICFLAGS=-fPIC\nCXX20PICFLAGS=-fPIC\nFPICFLAGS=-fPIC\nWe suggest only using these if the problem is encountered (it was not seen on CRAN with GCC 10 at the time of writing).\nNote that R may need to be re-compiled after even a minor update to the compiler (e.g. from 10.1 to 10.2) but this may not be clear from confused compiler messages.\n\n\n2.7.7 LTO with LLVM\nLLVM supports another type of LTO called ‘Thin LTO’ as well as a similar implementation to GCC, sometimes called ‘Full LTO’. (See https://clang.llvm.org/docs/ThinLTO.html.) Currently the LLVM compilers relevant to R are clang and flang for which this can be selected by setting macro LTO=-flto=thin. LLVM has\nAR=llvm-ar\nRANLIB=llvm-ranlib\n(but macOS does not, and these are not needed there). Where the linker supports a parallel backend for Thin LTO this can be specified via the macro LTO_LD: see the URL above for per-linker settings and further linking optimizations.)\nFor example, on macOS one might use\nLTO=-flto=thin\nLTO_FC=\nLTO_LD=-Wl,-mllvm,-threads=4\nto use Thin LTO with 4 threads for C/C++ code, but skip LTO for Fortran code compiled with gfortran.\nIt is said to be particularly beneficial to use -O3 for clang in conjunction with LTO.\nIt seems that flang may support LTO, but with no documentation as yet.\nThe 2020s versions of Intel’s C/C++ compilers are based on LLVM and as such support LLVM-style LTO, both ‘full’ and ‘thin’. This might use something like\nLTO=-flto=thin -flto-jobs=8\n\n\n2.7.8 LTO for package checking\nLTO effectively compiles all the source code in a package as a single compilation unit and so allows the compiler (with sufficient diagnostic flags such as -Wall) to check consistency between what are normally separate compilation units.\nWith gcc/gfortran 9.x and later16 LTO will flag inconsistencies in calls to Fortran subroutines/functions, both between Fortran source files and between Fortran and C/C++. gfortran 8.4, 9.2 and later can help understanding these by extracting C prototypes from Fortran source files with option -fc-prototypes-external, e.g. that (at the time of writing) Fortran LOGICAL corresponds to int_least32_t * in C.16 probably also 8.4 and later." }, { "objectID": "Installing-R-under-Unix-alikes.html#testing-an-installation", diff --git a/r-exts/Creating-R-packages.html b/r-exts/Creating-R-packages.html index 171033c..43214fc 100644 --- a/r-exts/Creating-R-packages.html +++ b/r-exts/Creating-R-packages.html @@ -1709,7 +1709,7 @@

89 and tested at runtime (not least as the Java installation when the package is installed might not be the same as when the package is run and will not be for binary packages).

When specifying a minimum Java version please use the official version names, which are (confusingly)

-
1.1 1.2 1.3 1.4 5.0 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 (announced 21)
+
1.1 1.2 1.3 1.4 5.0 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

and as from 2018 a year.month scheme such as 18.9 is also in use. Fortunately only the integer values are likely to be relevant. If at all possible, use one of the LTS versions (8, 11, 17, 21 …) as the minimum version. The preferred form of version specification is

SystemRequirements: Java (>= 11)

A suitable test for Java at least version 8 for packages using rJava would be something like

diff --git a/r-exts/The-R-API.html b/r-exts/The-R-API.html index 20724a1..ce0dbc0 100644 --- a/r-exts/The-R-API.html +++ b/r-exts/The-R-API.html @@ -401,9 +401,9 @@ 

char * CallocCharBuf(size_t n)
-void * Memcpy(p, q, n)
-void * Memzero(p, m)
-

CallocCharBuf is shorthand for R_Calloc(n+1, char) to allow for the nul terminator. Memcpy and Memzero take n items from array p and copy them to array p or zero them respectively.

+void * Memcpy(q, p, n) +void * Memzero(p, n) +

CallocCharBuf(n) is shorthand for R_Calloc(n+1, char) to allow for the nul terminator. Memcpy and Memzero take n items from array p and copy them to array q or zero them respectively.

diff --git a/r-exts/search.json b/r-exts/search.json index a89b694..e7034aa 100644 --- a/r-exts/search.json +++ b/r-exts/search.json @@ -53,7 +53,7 @@ "href": "Creating-R-packages.html#writing-portable-packages", "title": "1  Creating R packages", "section": "1.6 Writing portable packages", - "text": "1.6 Writing portable packages\nThis section contains advice on writing packages to be used on multiple platforms or for distribution (for example to be submitted to a package repository such as CRAN).\nPortable packages should have simple file names: use only alphanumeric ASCII characters and period (.), and avoid those names not allowed under Windows (see Package structure).\nMany of the graphics devices are platform-specific: even X11() (aka x11()) which although emulated on Windows may not be available on a Unix-alike (and is not the preferred screen device on OS X). It is rarely necessary for package code or examples to open a new device, but if essential,72 use dev.new().72 People use dev.new() to open a device at a particular size: that is not portable but using dev.new(noRStudioGD = TRUE) helps.\nUse R CMD build to make the release .tar.gz file.\nR CMD check provides a basic set of checks, but often further problems emerge when people try to install and use packages submitted to CRAN – many of these involve compiled code. Here are some further checks that you can do to make your package more portable.\n\nIf your package has a configure script, provide a configure.win or configure.ucrt script to be used on Windows (an empty configure.win file if no actions are needed).\nIf your package has a Makevars or Makefile file, make sure that you use only portable make features. Such files should be LF-terminated73 (including the final line of the file) and not make use of GNU extensions. (The POSIX specification is available at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html; anything not documented there should be regarded as an extension to be avoided. Further advice can be found at https://www.gnu.org/software/autoconf/manual/autoconf.html#Portable-Make. ) Commonly misused GNU extensions are conditional inclusions (ifeq and the like), ${shell ...}, ${wildcard ...} and similar, and the use of +=74 and :=. Also, the use of $< other than in implicit rules is a GNU extension, as is the $^ macro. As is the use of .PHONY (some other makes ignore it). Unfortunately makefiles which use GNU extensions often run on other platforms but do not have the intended results.\nNote that the -C flag for make is not included in the POSIX specification and is not implemented by some of the makes which have been used with R.\nThe use of ${shell ...} can be avoided by using backticks, e.g.\nPKG_CPPFLAGS = `gsl-config --cflags`\nwhich works in all versions of make known75 to be used with R.\nIf you really must require GNU make, declare it in the DESCRIPTION file by\nSystemRequirements: GNU make\nand ensure that you use the value of environment variable MAKE (and not just make) in your scripts. (On some platforms GNU make is available under a name such as gmake, and there SystemRequirements is used to set MAKE.)\nIf you only need GNU make for parts of the package which are rarely needed (for example to create bibliography files under vignettes), use a file called GNUmakefile rather than Makefile as GNU make (only) will use the former.\nmacOS has used GNU make for many years (it previously used BSD make), but the version has been frozen at 3.81 (from 2006).\nSince the only viable make for Windows is GNU make, it is permissible to use GNU extensions in files Makevars.win, Makevars.ucrt, Makefile.win or Makefile.ucrt.\nIf you use src/Makevars to compile code in a subdirectory, ensure that you have followed all the advice above. In particular\n\nAnticipate a parallel make. See Using Makevars.\nPass macros down to the makefile in the subdirectory, including all the needed compiler flags (including PIC and visibility flags). If they are used in the subdirectory’s Makefile, this includes macros AR and RANLIB. See Compiling in sub-directories, which has a C example. A C++ example: makefile pkg/libpkg.a: (cd pkg && $(MAKE) -f make_pkg libpkg.a \\ CXX=\"$(CXX)\" CXXFLAGS=\"$(CXXFLAGS) $(CXXPICFLAGS) $(C_VISIBILITY)\" \\ AR=\"$(AR)\" RANLIB=\"$(RANLIB)\")\nEnsure that cleanup will be performed by R CMD build, for example in a cleanup script or a clean target.\n\nIf your package uses a src/Makefile file to compile code to be linked into R, ensure that it uses exactly the same compiler and flag settings that R uses when compiling such code: people often forget PIC flags. If R CMD config is used, this needs something like (for C++) makefile RBIN = `\"${R_HOME}/bin/R\"` CXX = `\"${RBIN}\" CMD config CXX` CXXFLAGS = `\"${RBIN}\" CMD config CXXFLAGS` `\"${RBIN}\" CMD config CXXPICFLAGS`\nNames of source files including = (such as src/complex_Sig=gen.c) will confuse some make programs and should be avoided.\nBash extensions also need to be avoided in shell scripts, including expressions in Makefiles (which are passed to the shell for processing). Some R platforms use strict76 Bourne shells: an earlier R toolset on Windows77 and some Unix-alike OSes use ash (https://en.wikipedia.org/wiki/Almquist_shell, a ’lightweight shell with few builtins) or derivatives such as dash. Beware of assuming that all the POSIX command-line utilities are available, especially on Windows where only a subset (which has changed by version of Rtools) is provided for use with R. One particular issue is the use of echo, for which two behaviours are allowed (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/echo.html) and both have occurred as defaults on R platforms: portable applications should use neither -n (as the first argument) nor escape sequences. The recommended replacement for echo -n is the command printf. Another common issue is the construction\nexport FOO=value\nwhich is bash-specific (first set the variable then export it by name).\nUsing test -e (or [ -e ]) in shell scripts is not fully portable78: -f is normally what is intended. Flags -a and -o are nowadays declared obsolescent by POSIX and should not be used.\nUse of ‘brace expansion’, e.g.,\nrm -f src/*.{o,so,d}\nis not portable.\nThe -o flag for set in shell scripts is optional in POSIX and not supported on all the platforms R is used on.\nThe variable OSTYPE is shell-specific and its values are rather unpredictable and may include a version such as darwin19.0: uname is often what is intended (with common values Darwin, Linux and SunOS).\nOn macOS which shell /bin/sh invokes is user- and platform-dependent: it might be bash version 3.2, dash or zsh (for new accounts it is zsh, for accounts ported from Mojave or earlier it is usually bash).\nMake use of the abilities of your compilers to check the standards-conformance of your code. For example, gcc, clang and gfortran79 can be used with options -Wall -pedantic to alert you to potential problems. This is particularly important for C++, where g++ -Wall -pedantic will alert you to the use of some of the GNU extensions which fail to compile on most other C++ compilers. If R was not configured accordingly, one can achieve this via personal Makevars files. See section ‘Customizing package compilation’ in the ‘R Installation and Administration’ manual for more information.\nPortable C++ code needs to follow both the 2011, 2014 and 2017 standards or to specify C+11/14/17/20 where available (which is not the case on all R platforms). Currently C++20 support is patchy across R platforms.\nIf using Fortran with the GNU compiler, use the flags -std=f95 -Wall -pedantic which reject most GNU extensions and features from later standards. (Although R only requires Fortran 90, gfortran does not have a way to specify that standard.) Also consider -std=f2008 as some recent compilers have Fortran 2008 or even 2018 as the minimum supported standard.\nNot all common R platforms conform to the expected standards, e.g. C99 for C code. One common area of problems is the *printf functions where Windows did not support %lld, %Lf and similar formats (and has its own formats such as %I64d for 64-bit integers). It is very rare to need to output such types, and 64-bit integers can usually be converted to doubles for output. However, the C11 standard (section 7.8.1) includes PRIxNN macros80 in C header inttypes.h (for example PRId64) so the portable approach is to test for these and if not available provide emulations in the package.\nAs from macOS 11 (late 2020), its C compiler sets the flag -Werror=implicit-function-declaration by default which forces stricter conformance to C99. This can be used on other platforms with gcc or clang. If your package has a (autoconf-generated) configure script, try installing it whilst using this flag, and read through the config.log file — compilation warnings and errors can lead to features which are present not being detected. (If possible do this on several platforms.)\nR CMD check performs some checks for non-portable compiler/linker flags in src/Makevars. However, it cannot check the meaning of such flags, and some are commonly accepted but with compiler-specific meanings. There are other non-portable flags which are not checked, nor are src/Makefile files and makefiles in sub-directories. As a comment in the code says\n\nIt is hard to think of anything apart from -I* and -D* that is safe for general use …\n\nalthough -pthread is pretty close to portable. (Option -U is portable but little use on the command line as it will only cancel built-in defines (not portable) and those defined earlier on the command line (R does not use any).)\nPeople have used configure to customize src/Makevars, including for specific compilers. This is unsafe for several reasons. First, unintended compilers might meet the check—for example, several compilers other than GCC identify themselves as ‘GCC’ whilst being only partially conformant. Second, future versions of compilers may behave differently (including updates to quite old series) so for example -Werror (and specializations) can make a package non-installable under a future version. Third, using flags to suppress diagnostic messages can hide important information for debugging on a platform not tested by the package maintainer. (R CMD check can optionally report on unsafe flags which were used.)\nAvoid the use of -march and especially -march=native. This allows the compiler to generate code that will only run on a particular class of CPUs (that of the compiling machine for native). People assume this is a ‘minimum’ CPU specification, but that is not how it is documented for gcc (it is accepted by clang but apparently it is undocumented what precisely it does, and it can be accepted and may be ignored for other compilers). (For personal use -mtune is safer, but still not portable enough to be used in a public package.) Not even gcc supports native for all CPUs, and it can do surprising things if it finds a CPU released later than its version.\nDo be very careful with passing arguments between R, C and Fortran code. In particular, long in C will be 32-bit on some R platforms (including 64-bit Windows), but 64-bit on most modern Unix and Linux platforms. It is rather unlikely that the use of long in C code has been thought through: if you need a longer type than int you should use a configure test for a C99/C++11 type such as int_fast64_t (and failing that, long long) and typedef your own type, or use another suitable type (such as size_t, but beware that is unsigned and ssize_t is not portable).\nIt is not safe to assume that long and pointer types are the same size, and they are not on 64-bit Windows. If you need to convert pointers to and from integers use the C99/C++11 integer types intptr_t and uintptr_t (in the headers <stdint.h> and <cstdint>: they are not required to be implemented by the standards but are used in C code by R itself).\nNote that integer in Fortran corresponds to int in C on all R platforms.\nUnder no circumstances should your compiled code ever call abort or exit81: these terminate the user’s R process, quite possibly losing all unsaved work. One usage that could call abort is the assert macro in C or C++ functions, which should never be active in production code. The normal way to ensure that is to define the macro NDEBUG, and R CMD INSTALL does so as part of the compilation flags. Beware of including headers (including from other packages) which could undefine it, now or in future versions. If you wish to use assert during development. you can include -UNDEBUG in PKG_CPPFLAGS or #undef it in your headers or code files. Note that your own src/Makefile or makefiles in sub-directories may also need to define NDEBUG.\nThis applies not only to your own code but to any external software you compile in or link to.\nCompiled code should not write to stdout or stderr and C++ and Fortran I/O should not be used. As with the previous item such calls may come from external software and may never be called, but package authors are often mistaken about that.\nCompiled code should not call the system random number generators such as rand, drand48 and random82, but rather use the interfaces to R’s RNGs described in Random number generation. In particular, if more than one package initializes a system RNG (e.g. via srand), they will interfere with each other. This applies also to Fortran 90’s random_number and random_seed, and Fortran 2018’s random_init. And to GNU Fortran’s rand, irand and srand. Except for drand48, what PRNG these functions use is implementation-dependent.\nNor should the C++11 random number library be used nor any other third-party random number generators such as those in GSL.\nUse of sprintf and vsprintf is regarded as a potential security risk and warned about on some platforms.83 R CMD check reports if any calls are found.\nErrors in memory allocation and reading/writing outside arrays are very common causes of crashes (e.g., segfaults) on some machines. See Checking memory access for tools which can be used to look for this.\nMany platforms will allow unsatisfied entry points in compiled code, but will crash the application (here R) if they are ever used. Some (notably Windows) will not. Looking at the output of\nnm -pg mypkg.so\nand checking if any of the symbols marked U is unexpected is a good way to avoid this.\nLinkers have a lot of freedom in how to resolve entry points in dynamically-loaded code, so the results may differ by platform. One area that has caused grief is packages including copies of standard system software such as libz (especially those already linked into R). In the case in point, entry point gzgets was sometimes resolved against the old version compiled into the package, sometimes against the copy compiled into R and sometimes against the system dynamic library. The only safe solution is to rename the entry points in the copy in the package. We have even seen problems with entry point name myprintf, which is a system entry point84 on some Linux systems.\nA related issue is the naming of libraries built as part of the package installation. macOS and Windows have case-insensitive file systems, so using\n-L. -lLZ4\nin PKG_LIBS will match liblz4. And -L. only appends to the list of searched locations, and liblz4 might be found in an earlier-searched location (and has been). The only safe way is to give an explicit path, for example\n./libLZ4.a\nConflicts between symbols in DLLs are handled in very platform-specific ways. Good ways to avoid trouble are to make as many symbols as possible static (check with nm -pg), and to use names which are clearly tied to your package (which also helps users if anything does go wrong). Note that symbol names starting with R_ are regarded as part of R’s namespace and should not be used in packages.\nIt is good practice for DLLs to register their symbols (see Registering native routines), restrict visibility (see Controlling visibility) and not allow symbol search (see Registering native routines). It should be possible for a DLL to have only one visible symbol, R_init_pkgname, on suitable platforms85, which would completely avoid symbol conflicts.\nIt is not portable to call compiled code in R or other packages via .Internal, .C, .Fortran, .Call or .External, since such interfaces are subject to change without notice and will probably result in your code terminating the R process.\nDo not use (hard or symbolic) file links in your package sources. Where possible R CMD build will replace them by copies.\nIf you do not yourself have a Windows system, consider submitting your source package to WinBuilder (https://win-builder.r-project.org/) before distribution. If you need to check on an M1 Mac, there is a check service at https://mac.r-project.org/macbuilder/submit.html.\nIt is bad practice for package code to alter the search path using library, require or attach and this often does not work as intended. For alternatives, see Suggested packages and with().\nExamples can be run interactively via example as well as in batch mode when checking. So they should behave appropriately in both scenarios, conditioning by interactive() the parts which need an operator or observer. For instance, progress bars86 are only appropriate in interactive use, as is displaying help pages or calling View() (see below).\nBe careful with the order of entries in macros such as PKG_LIBS. Some linkers will re-order the entries, and behaviour can differ between dynamic and static libraries. Generally -L options should precede87 the libraries (typically specified by -l options) to be found from those directories, and libraries are searched once in the order they are specified. Not all linkers allow a space after -L .\nCare is needed with the use of LinkingTo. This puts one or more directories on the include search path ahead of system headers but (prior to R 3.4.0) after those specified in the CPPFLAGS macro of the R build (which normally includes -I/usr/local/include, but most platforms ignore that and include it with the system headers).\nAny confusion would be avoided by having LinkingTo headers in a directory named after the package. In any case, name conflicts of headers and directories under package include directories should be avoided, both between packages and between a package and system and third-party software.\nThe ar utility is often used in makefiles to make static libraries. Its modifier u is defined by POSIX but is disabled in GNU ar on some Linux distributions which use ‘deterministic mode’. The safest way to make a static library is to first remove any existing file of that name then use ar -cr and then ranlib if needed (which is system-dependent: on most systems88 ar always maintains a symbol table). The POSIX standard says options should be preceded by a hyphen (as in -cr), although most OSes accept them without. Note that on some systems ar -cr must have at least one file specified.\nThe s modifier (to replace a separate call to ranlib) is required by X/OPEN but not POSIX, so ar -crs is not portable.\nThe strip utility is platform-specific (and CRAN prohibits removing debug symbols). For example the options --strip-debug and --strip-unneeded of the GNU version are not supported on macOS: the POSIX standard for strip does not mention any options, and what calling it without options does is platform-dependent. Stripping a .so file could even prevent it being dynamically loaded into R on an untested platform.\nld -S invokes strip --strip-debug for GNU ld (and similarly on macOS) but is not portable: in particular on Solaris it did something completely different and took an argument.\nSome people have a need to set a locale. Locale names are not portable, and e.g. fr_FR.utf8 is commonly used on Linux but not accepted on macOS. fr_FR.UTF-8 is more portable, being accepted on recent Linux, AIX, FreeBSD, macOS and Solaris (at least). However, some Linux distributions micro-package, so locales defined by glibc (including these examples) may not be installed.\nAvoid spaces in file names, not least as they can cause difficulties for external tools. An example was a package with a knitr vignette that used spaces in plot names: this caused some older versions of pandoc to fail with a baffling error message.\nNon-ASCII filenames can also cause problems (particularly in non-UTF-8 locales).\nTake care in naming LaTeX macros (also known as ‘commands’) in vignette sources: if these are also defined in a future version of one of the LaTeX packages used there will be a fatal error. One instance in 2021 was package hyperref newly defining \\C, \\F, \\G, \\U and \\textapprox. If you are confident that your definitions will be the only ones relevant you can use \\renewcommand but it is better to use names clearly associated with your package.\nMake sure that any version requirement for Java code is both declared in the SystemRequirements field89 and tested at runtime (not least as the Java installation when the package is installed might not be the same as when the package is run and will not be for binary packages).\nWhen specifying a minimum Java version please use the official version names, which are (confusingly)\n1.1 1.2 1.3 1.4 5.0 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 (announced 21)\nand as from 2018 a year.month scheme such as 18.9 is also in use. Fortunately only the integer values are likely to be relevant. If at all possible, use one of the LTS versions (8, 11, 17, 21 …) as the minimum version. The preferred form of version specification is\nSystemRequirements: Java (>= 11)\nA suitable test for Java at least version 8 for packages using rJava would be something like\n.jinit()\njv <- .jcall(\"java/lang/System\", \"S\", \"getProperty\", \"java.runtime.version\")\nif(substr(jv, 1L, 2L) == \"1.\") {\n jvn <- as.numeric(paste0(strsplit(jv, \"[.]\")[[1L]][1:2], collapse = \".\"))\n if(jvn < 1.8) stop(\"Java >= 8 is needed for this package but not available\")\n}\nJava 9 changed the format of this string (which used to be something like 1.8.0_292-b10); Java 11 gave jv as 11+28 whereas Java 11.0.11 gave 11.0.11+9. (https://openjdk.org:443/jeps/322 details the current scheme. Note that it is necessary to allow for pre-releases like 11-ea+22.)\nNote too that the compiler used to produce a jar can impose a minimum Java version, often resulting in an arcane message like\njava.lang.UnsupportedClassVersionError: ... Unsupported major.minor version 52.0\n(Where https://en.wikipedia.org/wiki/Java_class_file maps class-file version numbers to Java versions.) Compile with something like javac -target 11 to ensure this is avoided. Note this also applies to packages distributing (or even downloading) compiled Java code produced by others, so their requirements need to be checked (they are often not documented accurately) and accounted for. It should be possible to check the class-file version via command-line utility javap, if necessary after extracting the .class files from a .jar archive. For example,\njar xvf some.jar\njavap -verbose path/to/some.class | grep major\nSome packages have stated a requirement on a particular JDK, but a package should only be requiring a JRE unless providing its own Java interface.\nJava 8 is still in widespread use (and may remain so because of licence changes and support on older OSes: OpenJDK has security support until March 2026). On the other hand, newer platforms may only have support for recent versions of Java: for arm64 macOS the first officially supported version was\n\n\n\nA package with a hard-to-satisfy system requirement is by definition not portable, annoyingly so if this is not declared in the SystemRequirements field. The most common example is the use of pandoc, which is only available for a very limited range of platforms (and has onerous requirements to install from source) and has capabilities90 that vary by build but are not documented. Several recent versions of pandoc for macOS did not work on R’s then target of High Sierra (and this too was undocumented). Another example is the Rust compilation system (cargo and rustc).\nUsage of external commands should always be conditional on a test for presence (perhaps using Sys.which), as well as declared in the SystemRequirements field. A package should pass its checks without warnings nor errors without the external command being present.\nAn external command can be a (possibly optional) requirement for an imported or suggested package but needed for examples, tests or vignettes in the package itself. Such usages should always be declared and conditional.\nInterpreters for scripting languages such as Perl, Python and Ruby need to be declared as system requirements and used conditionally: for example macOS 10.16 was announced not to have them (but released as macOS 11 with them); later it was announced that macOS 12.3 does not have Python 2 and only a minimal install of Python 3 is included. Python 2 has passed end-of-life and been removed from many major distributions. Support for Rust or Go cannot be assumed.\nCommand cmake is not commonly installed, and where it is, it might not be on the path. In particular, the most common location on macOS is /Applications/CMake.app/Contents/bin/cmake and that should be looked for if cmake is not found on the path.\nBe sure to use portable encoding names: none of utf8, mac and macroman is portable. See the help for file for more details.\nDo not invoke R by plain R, Rscript or (on Windows) Rterm in your examples, tests, vignettes, makefiles or other scripts. As pointed out in several places earlier in this manual, use something like\n\"$(R_HOME)/bin/Rscript\"\n\"$(R_HOME)/bin$(R_ARCH_BIN)/Rterm\"\nwith appropriate quotes (as, although not recommended, R_HOME can contain spaces).\nDo not use R_HOME in makefiles except when passing them to the shell. Specifically, do not use R_HOME in the argument to include, as R_HOME can contain spaces. Quoting the argument to include does not help. A portable and the recommended way to avoid the problem of spaces in ${R_HOME} is using option -f of make. This is easy to do with recursive invocation of make, which is also the only usual situation when R_HOME is needed in the argument for include. makefile $(MAKE) -f \"${R_HOME}/etc${R_ARCH}/Makeconf\" -f Makefile.inner\nIf distributing datasets involving date-times, consider if a time zone needs to be specified. The most portable way to distribute date-times is as objects of class \"POSIXct\" and as these record the time in UTC, the time represented is independent of the time zone: but how it is printed may not be. Objects of class \"POSIXlt\" should have a \"tzone\" attribute. Dates (e.g, birthdays) are conventionally considered independently of time zone.\nIf at all possible avoid any Internet access during package installation. Installation and use may well be on different machines/accounts and those allowed to install software may have no Internet access, and being self-contained helps ensure long-term reproducibility.\n\n73 Solaris make did not accept CRLF-terminated Makefiles; Solaris warned about and some other makes ignore incomplete final lines.74 This was apparently introduced in SunOS 4, and is available elsewhere provided it is surrounded by spaces.75 GNU make, BSD make and other variants of pmake in FreeBSD, NetBSD and formerly in macOS, and formerly AT&T make as implemented on Solaris and ‘Distributed Make’ (dmake), part of Oracle Developer Studio and available in other versions including from Apache OpenOffice.76 For example, test options -a and -e are not portable, and not supported in the AT&T Bourne shell used on Solaris 10/11, even though they are in the POSIX standard. Nor did Solaris support $(cmd).77 as from R 4.0.0 the default is bash.78 it was not in the Bourne shell, and was not supported by Solaris 10.79 https://fortranwiki.org/fortran/show/Modernizing+Old+Fortran may help explain some of the warnings from gfortran -Wall -pedantic.80 These are optional because the corresponding types are, but must be provided if the types are.81 or where supported the variants _Exit and _exit.82 This and srandom are in any case not portable. They are in POSIX but not in the C99 standard, and not available on Windows.83 including macOS as from version 13.84 in libselinux.85 At least Linux and Windows, but not macOS.86 except perhaps the simplest kind as used by download.file() in non-interactive use.87 Whereas the GNU linker reorders so -L options are processed first, the Solaris one did not.88 some versions of macOS did not.89 If a Java interpreter is required directly (not via rJava) this must be declared and its presence tested like any other external command.90 For example, the ability to handle https:// URLs.Do be careful in what your tests (and examples) actually test. Bad practice seen in distributed packages include:\n\nIt is not reasonable to test the time taken by a command: you cannot know how fast or how heavily loaded an R platform might be. At best you can test a ratio of times, and even that is fraught with difficulties and not advisable: for example, the garbage collector may trigger at unpredictable times following heuristics that may change without notice.\nDo not test the exact format of R messages (from R itself or from other packages): They change, and they can be translated.\nPackages have even tested the exact format of system error messages, which are platform-dependent and perhaps locale-dependent. For example, in late 2021 libcurl changed its warning/error messages, including when URLs are not found.\nIf you use functions such as View, remember that in testing there is no one to look at the output. It is better to use something like one of\nif(interactive()) View(obj) else print(head(obj))\nif(interactive()) View(obj) else str(obj)\nBe careful when comparing file paths. There can be multiple paths to a single file, and some of these can be very long character strings. If possible canonicalize paths before comparisons, but study ?normalizePath to be aware of the pitfalls.\nOnly test the accuracy of results if you have done a formal error analysis. Things such as checking that probabilities numerically sum to one are silly: numerical tests should always have a tolerance. That the tests on your platform achieve a particular tolerance says little about other platforms. R is configured by default to make use of long doubles where available, but they may not be available or be too slow for routine use. Most R platforms use ix86 or x86_64 CPUs: these may use extended precision registers on some but not all of their FPU instructions. Thus the achieved precision can depend on the compiler version and optimization flags—our experience is that 32-bit builds tend to be less precise than 64-bit ones. But not all platforms use those CPUs, and not all91 which use them configure them to allow the use of extended precision. In particular, current ARM CPUs do not have extended precision nor long doubles, and clang currently has long double the same as double on all ARM CPUs. On the other hand some CPUs have higher-precision modes which may be used for long double, notably 64-bit PowerPC and Sparc.\nIf you must try to establish a tolerance empirically, configure and build R with --disable-long-double and use appropriate compiler flags (such as -ffloat-store and -fexcess-precision=standard for gcc, depending on the CPU type92) to mitigate the effects of extended-precision calculations. The platform most often seen to give different numerical results is arm64 macOS, so be sure to include that in any empirical determination.\nTests which involve random inputs or non-deterministic algorithms should normally set a seed or be tested for many seeds.\nTests should use options(warn = 1) as reporting\nThere were 22 warnings (use warnings() to see them)\nis pointless, especially for automated checking systems.\nIf your package uses dates/times, ensure that it works in all timezones, especially those near boundaries (problems have most often be seen in Europe/London (zero offset in Winter) and Pacific/Auckland, near enough the International Date line) and with offsets not in whole hours (Adelaide, Chatham Islands, …). More extreme examples are Africa/Conakry (permanent UTC), Asia/Calcutta (no DST, permanent half-hour offset) and Pacific/Kiritimati(no DST, more than 12 hours ahead of UTC).\n\n91 Not doing so is the default on Windows, overridden for the R executables.92 These are not needed for the default compiler settings on x86_64 but are likely to be needed on ix86.\n1.6.1 PDF size\nThere are a several tools available to reduce the size of PDF files: often the size can be reduced substantially with no or minimal loss in quality. Not only do large files take up space: they can stress the PDF viewer and take many minutes to print (if they can be printed at all).\nqpdf (https://qpdf.sourceforge.io/) can compress losslessly. It is fairly readily available (e.g. it has binaries for Windows and packages in Debian/Ubuntu/Fedora, and is installed as part of the CRAN macOS distribution of R). R CMD build has an option to run qpdf over PDF files under inst/doc and replace them if at least 10Kb and 10% is saved. The full path to the qpdf command can be supplied as environment variable R_QPDF (and is on the CRAN binary of R for macOS). It seems MiKTeX does not use PDF object compression and so qpdf can reduce considerably the sizes of files it outputs: MiKTeX’s defaults can be overridden by code in the preamble of an Sweave or LaTeX file — see how this is done for the R reference manual at https://svn.r-project.org/R/trunk/doc/manual/refman.top.\nOther tools can reduce the size of PDFs containing bitmap images at excessively high resolution. These are often best re-generated (for example Sweave defaults to 300 ppi, and 100–150 is more appropriate for a package manual). These tools include Adobe Acrobat (not Reader), Apple’s Preview93 and Ghostscript (which converts PDF to PDF by93 Select ‘Save as’, and select ‘Reduce file size’ from the ‘Quartz filter’ menu’: this can be accessed in other ways, for example by Automator.\nps2pdf options -dAutoRotatePages=/None -dPrinted=false in.pdf out.pdf\nand suitable options might be\n-dPDFSETTINGS=/ebook\n-dPDFSETTINGS=/screen\nSee https://ghostscript.readthedocs.io/en/latest/VectorDevices.html for more such and consider all the options for image downsampling). There have been examples in CRAN packages for which current versions of Ghostscript produced much bigger reductions than earlier ones (e.g. at the upgrades from 9.50 to 9.52, from 9.55 to 9.56 and then to 10.00.0).\nWe come across occasionally large PDF files containing excessively complicated figures using PDF vector graphics: such figures are often best redesigned or failing that, output as PNG files.\nOption --compact-vignettes to R CMD build defaults to value qpdf: use both to try harder to reduce the size, provided you have Ghostscript available (see the help for tools::compactPDF).\n\n\n1.6.2 Check timing\nThere are several ways to find out where time is being spent in the check process. Start by setting the environment variable _R_CHECK_TIMINGS_ to 0. This will report the total CPU times (not Windows) and elapsed times for installation and running examples, tests and vignettes, under each sub-architecture if appropriate. For tests and vignettes, it reports the time for each as well as the total.\nSetting _R_CHECK_TIMINGS_ to a positive value sets a threshold (in seconds elapsed time) for reporting timings.\nIf you need to look in more detail at the timings for examples, use option --timings to R CMD check (this is set by --as-cran). This adds a summary to the check output for all the examples with CPU or elapsed time of more than 5 seconds. It produces a file mypkg.Rcheck/mypkg-Ex.timings containing timings for each help file: it is a tab-delimited file which can be read into R for further analysis.\nTimings for the tests and vignette runs are given at the bottom of the corresponding log file: note that log files for successful vignette runs are only retained if environment variable _R_CHECK_ALWAYS_LOG_VIGNETTE_OUTPUT_ is set to a true value.\n\n\n1.6.3 Encoding issues\nThe issues in this subsection have been much alleviated by the change in R 4.2.0 to running the Windows port of R in a UTF-8 locale where available. However, Windows users might be running an earlier version of R on an earlier version of Windows which does not support UTF-8 locales.\nCare is needed if your package contains non-ASCII text, and in particular if it is intended to be used in more than one locale. It is possible to mark the encoding used in the DESCRIPTION file and in .Rd files, as discussed elsewhere in this manual.\nFirst, consider carefully if you really need non-ASCII text. Some users of R will only be able to view correctly text in their native language group (e.g. Western European, Eastern European, Simplified Chinese) and ASCII.94. Other characters may not be rendered at all, rendered incorrectly, or cause your R code to give an error. For .Rd documentation, marking the encoding and including ASCII transliterations is likely to do a reasonable job. The set of characters which is commonly supported is wider than it used to be around 2000, but non-Latin alphabets (Greek, Russian, Georgian, …) are still often problematic and those with double-width characters (Chinese, Japanese, Korean, emoji) often need specialist fonts to render correctly.94 except perhaps some special characters such as backslash and hash which may be taken over for currency symbols.\nSeveral CRAN packages have messages in their R code in French (and a few in German). A better way to tackle this is to use the internationalization facilities discussed elsewhere in this manual.\nFunction showNonASCIIfile in package tools can help in finding non-ASCII bytes in files.\nThere is a portable way to have arbitrary text in character strings (only) in your R code, which is to supply them in Unicode as \\uxxxx escapes (or, rarely needed except for emojis, \\Uxxxxxxxx escapes). If there are any characters not in the current encoding the parser will encode the character string as UTF-8 and mark it as such. This applies also to character strings in datasets: they can be prepared using \\uxxxx escapes or encoded in UTF-8 in a UTF-8 locale, or even converted to UTF-8 via iconv(). If you do this, make sure you have R (>= 2.10) (or later) in the Depends field of the DESCRIPTION file.\nR sessions running in non-UTF-8 locales will if possible re-encode such strings for display (and this is done by RGui on older versions of Windows, for example). Suitable fonts will need to be selected or made available95 both for the console/terminal and graphics devices such as X11() and windows(). Using postscript or pdf will choose a default 8-bit encoding depending on the language of the UTF-8 locale, and your users would need to be told how to select the encoding argument.95 Typically on a Unix-alike this is done by telling fontconfig where to find suitable fonts to select glyphs from.\nNote that the previous two paragraphs only apply to character strings in R code. Non-ASCII characters are particularly prevalent in comments (in the R code of the package, in examples, tests, vignettes and even in the NAMESPACE file) but should be avoided there. Most commonly people use the Windows extensions to Latin-1 (often directional single and double quotes, ellipsis, bullet and en and em dashes) which are not supported in strict Latin-1 locales nor in CJK locales on Windows. A surprisingly common misuse is to use a right quote in don't instead of the correct apostrophe.\nDatasets can include marked UTF-8 or Latin-1 character strings. As R is nowadays unlikely to be run in a Latin-1 or Windows’ CP1252 locale, for performance reasons these should be converted to UTF-8.\nIf you want to run R CMD check on a Unix-alike over a package that sets a package encoding in its DESCRIPTION file and do not use a UTF-8 locale you may need to specify a suitable locale via environment variable R_ENCODING_LOCALES. The default is equivalent to the value\n\"latin1=en_US:latin2=pl_PL:UTF-8=en_US.UTF-8:latin9=fr_FR.iso885915@euro\"\n(which is appropriate for a system based on glibc: macOS requires latin9=fr_FR.ISO8859-15) except that if the current locale is UTF-8 then the package code is translated to UTF-8 for syntax checking, so it is strongly recommended to check in a UTF-8 locale.\n\n\n1.6.4 Portable C and C++ code\nWriting portable C and C++ code is mainly a matter of observing the standards (C99, C++14 or where declared C++11/17/20) and testing that extensions (such as POSIX functions) are supported. Do make maximal use of your compiler diagnostics — this typically means using flags -Wall and -pedantic for both C and C++ and additionally -Werror=implicit-function-declaration and -Wstrict-prototypes for C (on some platforms and compiler versions) these are part of -Wall or -pedantic).\nC++ standards: From version 3.6.0 (3.6.2 on Windows), R defaulted to C++11 where available96; from R 4.1.0 to C++14 and from R 4.3.0 to C++17 (where available). However, in earlier versions the default standard was that of the compiler used, often C++98 or C++14, and the default is likely to change in future. For maximal portability a package should either specify a standard (see Using C++ code) or be tested under all of C++11, C++98, C++14 and C++17. (Specifying C++14 or later will limit portability.)96 which it is on all known platforms, and is required as from R 4.0.0\nNote that the ‘TR1’ C++ extensions are not part of any of these standards and the <tr1/name> headers are not supplied by some of the compilers used for R, including on macOS. (Use the C++11 versions instead.)\nA common error is to assume recent versions of compilers or OSes. In production environments ‘long term support’ versions of OSes may be in use for many years,97 and their compilers may not be updated during that time. For example, GCC 4.8 was still in use in 2022 and could be (in RHEL 7) until 2028: that supports neither C++14 nor C++17.97 Ubuntu provides 5 years of support (but people were running 14.04 after 7 years) and RHEL provides 10 years full support and up to 14 with extended support.\nThe POSIX standards only require recently-defined functions to be declared if certain macros are defined with large enough values, and on some compiler/OS combinations98 they are not declared otherwise. So you may need to include something like one of98 This is seen on Linux, Solaris and FreeBSD, although each has other ways to turn on all extensions, e.g. defining _GNU_SOURCE, __EXTENSIONS__ or _BSD_SOURCE: the GCC compilers by default define _GNU_SOURCE unless a strict standard such as -std=c99 is used. On macOS extensions are declared unless one of these macros is given too small a value.\n#define _XOPEN_SOURCE 600\nor\n#ifdef __GLIBC__\n# define _POSIX_C_SOURCE 200809L\n#endif\nbefore any headers. (strdup, strncasecmp and strnlen are such functions – there were several older platforms which did not have the POSIX 2008 function strnlen.)\nHowever, some common errors are worth pointing out here. It can be helpful to look up functions at https://cplusplus.com/reference/ or https://en.cppreference.com/w/ and compare what is defined in the various standards.\nMore care is needed for functions such as mallinfo which are not specified by any of these standards—hopefully the man page on your system will tell you so. Searching online for such pages for various OSes (preferably at least Linux and macOS, and the FreeBSD manual pages at https://man.freebsd.org/cgi/man.cgi allow you to select many OSes) should reveal useful information but a configure script is likely to be needed to check availability and functionality.\nBoth the compiler and OS (via system header files, which may differ by architecture even for nominally the same OS) affect the compilability of C/C++ code. Compilers from the GCC, LLVM (clang and flang) Intel and Oracle Developer Studio suites have been used with R, and both LLVM clang and Oracle have more than one implementation of C++ headers and library. The range of possibilities makes comprehensive empirical checking impossible, and regrettably compilers are patchy at best on warning about non-standard code.\n\nMathematical functions such as sqrt are defined in C++11 for floating-point arguments: float, double, long double and possibly more. The standard specifies what happens with an argument of integer type but this is not always implemented, resulting in a report of ‘overloading ambiguity’: this was commonly seen on Solaris, but for pow also seen on macOS and other platforms using clang++.\nA not-uncommonly-seen problem is to mistakenly call floor(x/y) or ceil(x/y) for int arguments x and y. Since x/y does integer division, the result is of type int and ‘overloading ambiguity’ may be reported. Some people have (pointlessly) called floor and ceil on arguments of integer type, which may have an ‘overloading ambiguity’.\nA surprising common misuse is things like pow(10, -3): this should be the constant 1e-3. Note that there are constants such as M_SQRT2 defined via Rmath.h99 for sqrt(2.0), frequently mis-coded as sqrt(2).\nFunction fabs is defined only for floating-point types, except in C++11 and later which have overloads for std::fabs in <cmath> for integer types. Function abs is defined in C99’s <stdlib.h> for int and in C++’s <cstdlib> for integer types, overloaded in <cmath> for floating-point types. C++11 has additional overloads for std::abs in <cmath> for integer types. The effect of calling abs with a floating-point type is implementation-specific: it may truncate to an integer. For clarity and to avoid compiler warnings, use abs for integer types and fabs for double values, and when using C++ include <cmath> and use the std:: prefix.\nIt is an error (and make little sense, although has been seen) to call macros/functions isnan, isinf and isfinite for integer arguments: a few compilers give a compilation error. Function finite is obsolete, and some compilers will warn about its use100.\nThe GNU C/C++ compilers support a large number of non-portable extensions. For example, INFINITY (which is a float value in C99 and C++11), for which R provides the portable double value R_PosInf (and R_NegInf for -INFINITY). And NAN101 is just one NaN float value: for use with R, NA_REAL is often what is intended, but R_NaN is also available.\nSome (but not all) extensions are listed at https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html and https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Extensions.html.\nOther GNU extensions which have bitten package writers are the use of non-portable characters such as $ in identifiers and use of C++ headers under ext.\nitem Including C-style headers in C++ code is not portable. Including the legacy header102 math.h in C++ code may conflict with cmath which may be included by other headers. In C++11, functions like sqrt and isnan are defined for double arguments in math.h and for a range of types including double in cmath. Similar issues have been seen for stdlib.h and cstdlib. Including the C++ header first used to be a sufficient workaround but for some 2016 compilers only one could be included.\nBe careful to include the headers which define the functions you use. Some compilers/OSes include other system headers in their headers which are not required by the standards, and so code may compile on such systems and not on others. (A prominent example is the C++ header <random> which is indirectly included by <algorithm> by g++. Another issue is the C header <time.h> which is included by other headers on Linux and Windows but not macOS.) g++ 11 often needs explicit inclusion of the C++ headers <limits> (for numeric_limits) or <exception> (for set_terminate and similar), whereas earlier versions included these in other headers. g++ 13 requires the explicit inclusion of <cstdint> for types such as uint32_t which was previously included implicitly. (For more such, see https://gcc.gnu.org/gcc-13/porting_to.html.)\nNote that malloc, calloc, realloc and free are defined by C99 in the header stdlib.h and (in the std:: namespace) by C++ header cstdlib. Some earlier implementations used a header malloc.h, but that is not portable and does not exist on macOS.\nThis also applies to types such as ssize_t. The POSIX standards say that is declared in headers unistd.h and sys/types.h, and the latter is often included indirectly by other headers on some but not all systems.\nSimilarly for constants: for example SIZE_MAX is defined in stdint.h alongside size_t.\nSome headers are not portable: we have just mentioned malloc.h and often CRAN submissions attempt to use endian.h. The latter is a glibc extension: some OSs have machine/endian.h or sys/endian.h but some have neither.\nUse #include \"my.h\" not #include <my.h> for headers in your package. The second form is intended for system headers and the search order for such headers is platform-dependent (and may not include the current directory). For extra safety, name headers in a way that cannot be confused with a system header so not, for example, types.h.\nFor C++ code, be careful to specify namespaces where needed. Many functions are defined by the standards to be in the std namespace, but g++ puts many such also in the C++ main namespace. One way to do so is to use declarations such as\nusing std::floor;\nbut it is usually preferable to use explicit namespace prefixes in the code.\nExamples seen in CRAN packages include\nabs acos atan bind calloc ceil div exp fabs floor fmod free log malloc\nmemcpy memset pow printf qsort round sin sprintf sqrt strcmp strcpy\nstrerror strlen strncmp strtol tan trunc\nThis problem is less common than it used to be, but in 2019 LLVM clang did not have bind in the main namespace. Also seen has been type size_t defined only in the std namespace.\nNB: These functions are only guaranteed to be in the std namespace if the correct C++ header is included, e.g. <cmath> rather than <math.h>.\nIf you define functions in C++ which are inspired by later standards, put them in a namespace and refer to them using the namespace. We have seen conflicts with std::make_unique from C++14 and std::byte, std::data, std::sample and std::size from C++17.\nIn C++ code\nusing namesapace std; \nis not good practice, and has caused platform-dependent errors if included before headers, especially system headers (which may be included by other headers). The best practice is to use explicit std:: prefixes for all functions declared by the C++ standard to be in that namespace.\nSome C++ compilers refuse to compile constructs such as\n if(ptr > 0) { ....}\nwhich compares a pointer to the integer 0. This could just use if(ptr) (pointer addresses cannot be negative) but if needed pointers can be tested against nullptr (C++11) or NULL.\nMacros defined by the compiler/OS can cause problems. Identifiers starting with an underscore followed by an upper-case letter or another underscore are reserved for system macros and should not be used in portable code (including not as guards in C/C++ headers). Other macros, typically upper-case, may be defined by the compiler or system headers and can cause problems. Some of these can be avoided by defining _POSIX_C_SOURCE before including any system headers, but it is better to only use all-upper-case names which have a unique prefix such as the package name.\ntypedefs in OS headers can conflict with those in the package: examples have included ulong, index_t, single and thread. (Note that these may conflict with other uses as identifiers, e.g. defining a C++ function called single.) The POSIX standard reserves (in §2.2.2) all identifiers ending in _t.\nSome compilers do not allow a space between -D and the macro to be defined. Similarly for -U.\nIf you use OpenMP, check carefully that you have followed the advice in the subsection on OpenMP support. In particular, any use of OpenMP in C/C++ code will need to use\n#ifdef _OPENMP\n# include <omp.h>\n#endif\nAny use of OpenMP functions, e.g. omp_set_num_threads, also needs to be conditioned. To avoid incessant warnings such as\nwarning: ignoring #pragma omp parallel [-Wunknown-pragmas]\nuses of such pragmas should also be conditioned (or commented out if they are used in code in a package not enabling OpenMP on any platform).\nDo not hardcode -lgomp: not only is that specific to the GCC family of compilers, using the correct linker flag often sets up the run-time path to the library.\nPackage authors commonly assume things are part of C/C++ when they are not: the most common example is POSIX103 function strdup. The most common C library on Linux, glibc, will hide the declarations of such extensions unless a ‘feature-test macro’ is defined before (almost) any system header is included. So for strdup you need\n#define _POSIX_C_SOURCE 200809L\n...\n#include <string.h>\n...\nstrdup call(s)\nwhere the appropriate value can be found by man strdup on Linux. (Use of strncasecmp is similar.)\nHowever, modes of gcc with ‘GNU EXTENSIONS’ (which are the default, either -std=gnu99 or -std=gnu11) declare enough macros to ensure that missing declarations are rarely seen.\nThis applies also to constants such as M_PI and M_LN2, which are part of the X/Open standard: to use these define _XOPEN_SOURCE before including any headers, or include the R header Rmath.h.\nUsing alloca portably is tricky: it is neither an ISO C/C++ nor a POSIX function. An adequately portable preamble is\n#ifdef __GNUC__\n/* Includes GCC, clang and Intel compilers */\n# undef alloca\n# define alloca(x) __builtin_alloca((x))\n#elif defined(__sun) || defined(_AIX)\n/* this was necessary (and sufficient) for Solaris 10 and AIX 6: */\n# include <alloca.h>\n#endif\nCompiler writers feel free to implement features from later standards than the one specified, so for example they may implement or warn on C++14/17/20 features when C++11 is specified. Portable code will not use such features – it can be hard to know what they are but the most common warnings are\n'register' storage class specifier is deprecated and incompatible with C++17\n\nISO C++11 does not allow conversion from string literal to 'char *'\n(where conversion should be to const char *). Keyword register was not mentioned in C++98, deprecated in C++11 and removed in C++17.\nThere are quite a lot of other C++98 features deprecated in C++11 and removed in C++17, and LLVM clang 9 and later warn about them (and as from version 16 they have been removed). Examples include bind1st/bind2nd (use std::bind or lambdas104) std::auto_ptr (replaced by std::unique_ptr), std::mem_fun_ref and std::ptr_fun.\nLater versions of standards may add reserved words: for example bool, false and true became keywords in C23 and are no longer available as variable names. As noted above, C++17 uses byte, data, sample and size.\nSo avoid common words and keywords from other programming languages.\nBe careful about including C headers in C++ code. Issues include\n\nUse of the register storage class specifier (see the previous but one item).\nThe C99 keyword restrict is not part of105 any C++ standard and is rejected by some C++ compilers.\nInclusion by such headers of C-style headers such as math.h (see above).\n\nThe most portable way to interface to other software with a C API is to use C code (which can normally be mixed with C++ code in a package).\nreinterpret_cast in C++ is not safe for pointers: for example the types may have different alignment requirements. Use memcpy to copy the contents to a fresh variable of the destination type.\nAvoid platform-specific code if at all possible, but if you need to test for a platform ensure that all platforms are covered. For example, __unix__ is not defined on all Unix-alikes, in particular not on macOS. A reasonably portable way to condition code for a Unix-alike is\n#if defined (__unix__) || (defined (__APPLE__) && defined (__MACH__))\n#endif\nbut\n#ifdef _WIN32\n// Windows-specific code\n#else\n// Unix-alike code\n#endif\nwould be better. For a Unix-alike it is much better to use configure to test for the functionality needed than make assumptions about OSes (and people all too frequently forget R is used on platforms other than Linux, Windows and macOS — and some forget macOS).\nHeaders in subdirectories are often not portable. For C++, this includes bits/, tr1/ and tr2/, none of which exist on macOS (and ext/ exists there but with different content from g++-based platforms). Header bits/stdc++.h is both not portable and not recommended for end-user code even on platforms which include it.\nBe careful if using malloc or calloc. First, their return value must always be checked to see if the allocation succeeded – it is almost always easier to use R’s R_Calloc, which does check. Second, the first argument is of type size_t and recent compilers are warning about passing signed arguments (which could get promoted to ridiculously large values).\nFor C code, consider using the flag -Wstrict-prototypes which is supported by gcc and LLVM and Apple clang. This has found quite a number of errors where functions have been declared without arguments and is likely to become the default in future compilers. (It already is for LLVM clang in C23 mode.) Note that using f() for a function without any parameters was deprecated in C99 and C11, but it expected to be non-deprecated in C23. However, f(void) is supported by all standards and avoids any uncertainty.\nLLVM clang has a separate warning -Wdeprecated-non-prototype which is enabled by -Wstrict-prototypes. This warns on K&R-style usage, which will not be accepted in C23.\nSeveral C entry points are warned against in their man pages on most systems, often in very strong terms such as ‘Do not use these functions’. macOS has started to warn106 if these are used for sprintf, vsprintf, gets, mktemp, tempmam and tmpnam. It is highly recommended that you use safer alternatives (on any platform) but the warning can be avoided by defining _POSIX_C_SOURCE to for example 200809L before including the (C or C++) header which defines them. (However, this may hide other extensions.)\nCompilers may interpret comments in source code, so it is necessary to remove any intended for a compiler to interpret. The main example has been comments for Visual Fortran (as the Intel Fortran compiler has been known on Windows107) like\n!DEC$ ATTRIBUTES DLLEXPORT,C,REFERENCE,ALIAS:'kdenestmlcvb' :: kdenestmlcvb\nwhich are interpreted by Intel Fortran on all platforms (and are inappropriate for use with R on Windows). gfortran has similar forms starting with !GCC$.\nThe C++ new operator takes argument std::size_t size, which is unsigned. Using a signed integer type such as int may lead to compiler warnings such as\nwarning: argument 1 value '18446744073709551615' exceeds maximum object\n size 9223372036854775807 [-Walloc-size-larger-than=]\n(especially if LTO is used). So don’t do that!\n\n99 often taken from the toolchain’s headers.100 at the time of writing arm64 macOS both warned and did not supply a prototype in math.h which resulted in a compilation error.101 also part of C++11 and later.102 which often is the same as the header included by the C compiler, but some compilers have wrappers for some of the C headers.103 Although this is expected to be part of C23, full support of that is years away.104 https://stackoverflow.com/questions/32739018/a-replacement-for-stdbind2nd105 it is allowed but ignored in system headers.106 when using the macOS 13 SDK with a deployment target of macOS 13.107 and at one time as DEC Fortran, hence the DEC.Some additional information for C++ is available at https://journal.r-project.org/archive/2011-2/RJournal_2011-2_Plummer.pdf by Martyn Plummer.\n\n\n1.6.5 Common symbols\nMost OSes (including all those commonly used for R) have the concept of ‘tentative definitions’ where global C variables are defined without an initializer. Traditionally the linker resolves all tentative definitions of the same variable in different object files to the same object, or to a non-tentative definition. However, gcc 10108 and LLVM clang 11109 changed their default so that tentative definitions cannot be merged and the linker will give an error if the same variable is defined in more than one object file. To avoid this, all but one of the C source files should declare the variable extern — which means that any such variables included in header files need to be declared extern. A commonly used idiom (including by R itself) is to define all global variables as extern in a header, say globals.h (and nowhere else), and then in one (and one only) source file use108 see https://gcc.gnu.org/gcc-10/porting_to.html.109 See https://prereleases.llvm.org/11.0.0/rc2/tools/clang/docs/ReleaseNotes.html#modified-compiler-flags.\n#define extern\n# include \"globals.h\"\n#undef extern\nA cleaner approach is not to have global variables at all, but to place in a single file common variables (declared static) followed by all the functions which make use of them: this may result in more efficient code.\nThe ‘modern’ behaviour can be seen110 by using compiler flag -fno-common as part of CFLAGS in earlier versions of gcc and clang.110 In principle this could depend on the OS, but has been checked on Linux and macOS.\n-fno-common is said to be particularly beneficial for ARM cpus.\nThis is not pertinent to C++ which does not permit tentative definitions.\n\n\n1.6.6 C++17 issues\nR 4.3.0 and later default to C++17 when compiling C++, and that finally removed many C++98 features which were deprecated as long ago as C++11. Compiler/runtime authors have been slow to remove these, but LLVM clang with its libc++ runtime library finally started to do so in 2023 – some others warn but some do not.\nThe principal offender is the ‘Boost’ collection of C++ headers and libraries. There are two little-documented ways to work around aspects of its outdated code. One is to add\n-D_HAS_AUTO_PTR_ETC=0\nto PKG_CPPLAGS in src/Makevars, src/Makevars.win and src/Makevars.ucrt. This covers the removal of\nstd::auto_ptr\nstd::unary_function\nstd::binary_function\nstd::random_shuffle\nstd::binder1st\nstd::binder2nd\nwith most issues seen with code that includes boost/functional.hpp, usually indirectly.\nA rarer issue is the use of illegal values for enum types, usually negative ones such as\nBOOST_MPL_AUX_STATIC_CAST(AUX_WRAPPER_VALUE_TYPE, (value - 1));\nin boost/mpl/aux_/integral_wrapper.hpp. Adding\n -Wno-error=enum-constexpr-conversion\nto PKG_CXXFLAGS will allow this, but that flag is only accepted by recent versions of LLVM clang (and will not be in future) so needs a configure test.\nPre=built versions of current clang/libc++ are usually available from https://github.com/llvm/llvm-project/releases for a wide range of platforms (but the Windows builds there are not compatible with Rtools and the macOS ones are unsigned). To select libc++ add -stdlib=libc++ to CXX, for example by having\nCXX=\"/path/to/clang/clang++ -std=gnu++17 -stdlib=libc++\"\nin ~/.R/Makevars.\nAnother build for Windows which may be sufficiently compatible with Rtools can be found at https://github.com/mstorsjo/llvm-mingw: this uses libc++.\n\n\n1.6.7 Portable Fortran code\nUntil recently almost all known R platforms used gfortran as their Fortran compiler, but now there are LLVM and ‘classic’ flang and the Intel compilers ifort111 and ifx are free-of-change.111 announced to be discontinued in 2023.\nThere is still a lot of Fortran code in CRAN packages which predates Fortran 77. Modern Fortran compilers are being written to target a minimum standard of Fortran 2018. and it is desirable that Fortran code in packages complies with that standard. For gfortran this can be checked by adding -std=f2018 to FFLAGS. The most commonly seen issues are\n\nThe use of DFLOAT, which was superseded by DBLE in Fortran 77. Also, use of DCMPLX, DCONJG, DIMAG and similar.\nThe use of GNU Fortran extensions. Some are listed at https://gcc.gnu.org/onlinedocs/gfortran/Extensions-implemented-in-GNU-Fortran.html. Others which have caused problems include etime, getpid, isnan112 and sizeof.\nOne that frequently catches package writers is that it allows out-of-order declarations: in standard-conformant Fortran variables must be declared (explicitly or implicitly) before use in other declarations such as dimensions.\n\n112 There is a portable way to do this in Fortran 2003 (ieee_is_nan() in module ieee_arithmetic), but that was not supported in the versions 4.x of GNU Fortran. A pretty robust alternative is to test if(my_var /= my_var).Unfortunately this flags extensions such as DOUBLE COMPLEX and COMPLEX*16. R has tested that DOUBLE COMPLEX works and so is preferred to -COMPLEX*16. (One can also use something like -COMPLEX(KIND=KIND(0.0D0)).)\nGNU Fortran 10 and later give a compilation error for the previously widespread practice of passing a Fortran array element where an array is expected, or a scalar instead of a length-one array. See https://gcc.gnu.org/gcc-10/porting_to.html. As do the Intel Fortran compilers, and they can be stricter.\nThe use of IMPLICIT NONE is highly recommended – Intel compilers with -warn will warn on variables without an explicit type.\nCommon non-portable constructions include\n\nThe use of Fortran types such as REAL(KIND=8) is very far from portable. According to the standards this merely enumerates different supported types, so DOUBLE PRECISION might be REAL(KIND=3) (and is on an actual compiler). Even if for a particular compiler the value indicates the size in bytes, which values are supported is platform-specific — for example gfortran supports values of 4 and 8 on all current platforms and 10 and 16 on a few (but not for example on all arm CPUs).\nThe same applies to INTEGER(KIND=4) and COMPLEX(KIND=16).\nMany uses of integer and real variable in Fortran code in packages will interwork with C (for example .Fortran is written in C), and R has checked that INTEGER and DOUBLE PRECISION correspond to the C types int and double. To make this explicit, from Fortran 2003 one can use the named constants c_int, c_double and c_double_complex from module iso_c_binding.\nThe Intel compilers only recognize the extensions .f (fixed-form) and .f90 (free-form) and not .f95. R CMD INSTALL works around this for packages without a src/Makefile.\nUse of extensions .F and .F90 to indicate source code to be preprocessed: the preprocessor used is compiler-specific and may or may not be cpp.\n\n\n\n1.6.8 Binary distribution\nIf you want to distribute a binary version of a package on Windows or macOS, there are further checks you need to do to check it is portable: it is all too easy to depend on external software on your own machine that other users will not have.\nFor Windows, check what other DLLs your package’s DLL depends on (‘imports’ from in the DLL tools’ parlance). A convenient GUI-based tool to do so is ‘Dependency Walker’ (https://www.dependencywalker.com/) for both 32-bit and 64-bit DLLs – note that this will report as missing links to R’s own DLLs such as R.dll and Rblas.dll. The command-line tool objdump in the appropriate toolchain will also reveal what DLLs are imported from. If you use a toolchain other than one provided by the R developers or use your own makefiles, watch out in particular for dependencies on the toolchain’s runtime DLLs such as libgfortran, libstdc++ and libgcc_s.\nFor macOS, using R CMD otool -L on the package’s shared object(s) in the libs directory will show what they depend on: watch for any dependencies in /usr/local/lib or /usr/local/gfortran/lib, notably libgfortran.?.dylib and libquadmath.0.dylib. (For ways to fix these, see the section ‘Building binary packages’ in the ‘R Installation and Administration’ manual’.)\nMany people (including the CRAN package repository) will not accept source packages containing binary files as the latter are a security risk. If you want to distribute a source package which needs external software on Windows or macOS, options include\n\nTo arrange for installation of the package to download the additional software from a URL, as e.g. package Cairo used to.\nTo negotiate with Tomas Kalibera to include Windows software in Rtools or with Simon Urbanek to include macOS software in his ‘recipes’ system.\n(For CRAN.) To negotiate with Uwe Ligges to host the additional components on WinBuilder, and write a configure.win file to install them.\n\nBe aware that license requirements you may require you to supply the sources for the additional components (and will if your package has a GPL-like license)." + "text": "1.6 Writing portable packages\nThis section contains advice on writing packages to be used on multiple platforms or for distribution (for example to be submitted to a package repository such as CRAN).\nPortable packages should have simple file names: use only alphanumeric ASCII characters and period (.), and avoid those names not allowed under Windows (see Package structure).\nMany of the graphics devices are platform-specific: even X11() (aka x11()) which although emulated on Windows may not be available on a Unix-alike (and is not the preferred screen device on OS X). It is rarely necessary for package code or examples to open a new device, but if essential,72 use dev.new().72 People use dev.new() to open a device at a particular size: that is not portable but using dev.new(noRStudioGD = TRUE) helps.\nUse R CMD build to make the release .tar.gz file.\nR CMD check provides a basic set of checks, but often further problems emerge when people try to install and use packages submitted to CRAN – many of these involve compiled code. Here are some further checks that you can do to make your package more portable.\n\nIf your package has a configure script, provide a configure.win or configure.ucrt script to be used on Windows (an empty configure.win file if no actions are needed).\nIf your package has a Makevars or Makefile file, make sure that you use only portable make features. Such files should be LF-terminated73 (including the final line of the file) and not make use of GNU extensions. (The POSIX specification is available at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html; anything not documented there should be regarded as an extension to be avoided. Further advice can be found at https://www.gnu.org/software/autoconf/manual/autoconf.html#Portable-Make. ) Commonly misused GNU extensions are conditional inclusions (ifeq and the like), ${shell ...}, ${wildcard ...} and similar, and the use of +=74 and :=. Also, the use of $< other than in implicit rules is a GNU extension, as is the $^ macro. As is the use of .PHONY (some other makes ignore it). Unfortunately makefiles which use GNU extensions often run on other platforms but do not have the intended results.\nNote that the -C flag for make is not included in the POSIX specification and is not implemented by some of the makes which have been used with R.\nThe use of ${shell ...} can be avoided by using backticks, e.g.\nPKG_CPPFLAGS = `gsl-config --cflags`\nwhich works in all versions of make known75 to be used with R.\nIf you really must require GNU make, declare it in the DESCRIPTION file by\nSystemRequirements: GNU make\nand ensure that you use the value of environment variable MAKE (and not just make) in your scripts. (On some platforms GNU make is available under a name such as gmake, and there SystemRequirements is used to set MAKE.)\nIf you only need GNU make for parts of the package which are rarely needed (for example to create bibliography files under vignettes), use a file called GNUmakefile rather than Makefile as GNU make (only) will use the former.\nmacOS has used GNU make for many years (it previously used BSD make), but the version has been frozen at 3.81 (from 2006).\nSince the only viable make for Windows is GNU make, it is permissible to use GNU extensions in files Makevars.win, Makevars.ucrt, Makefile.win or Makefile.ucrt.\nIf you use src/Makevars to compile code in a subdirectory, ensure that you have followed all the advice above. In particular\n\nAnticipate a parallel make. See Using Makevars.\nPass macros down to the makefile in the subdirectory, including all the needed compiler flags (including PIC and visibility flags). If they are used in the subdirectory’s Makefile, this includes macros AR and RANLIB. See Compiling in sub-directories, which has a C example. A C++ example: makefile pkg/libpkg.a: (cd pkg && $(MAKE) -f make_pkg libpkg.a \\ CXX=\"$(CXX)\" CXXFLAGS=\"$(CXXFLAGS) $(CXXPICFLAGS) $(C_VISIBILITY)\" \\ AR=\"$(AR)\" RANLIB=\"$(RANLIB)\")\nEnsure that cleanup will be performed by R CMD build, for example in a cleanup script or a clean target.\n\nIf your package uses a src/Makefile file to compile code to be linked into R, ensure that it uses exactly the same compiler and flag settings that R uses when compiling such code: people often forget PIC flags. If R CMD config is used, this needs something like (for C++) makefile RBIN = `\"${R_HOME}/bin/R\"` CXX = `\"${RBIN}\" CMD config CXX` CXXFLAGS = `\"${RBIN}\" CMD config CXXFLAGS` `\"${RBIN}\" CMD config CXXPICFLAGS`\nNames of source files including = (such as src/complex_Sig=gen.c) will confuse some make programs and should be avoided.\nBash extensions also need to be avoided in shell scripts, including expressions in Makefiles (which are passed to the shell for processing). Some R platforms use strict76 Bourne shells: an earlier R toolset on Windows77 and some Unix-alike OSes use ash (https://en.wikipedia.org/wiki/Almquist_shell, a ’lightweight shell with few builtins) or derivatives such as dash. Beware of assuming that all the POSIX command-line utilities are available, especially on Windows where only a subset (which has changed by version of Rtools) is provided for use with R. One particular issue is the use of echo, for which two behaviours are allowed (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/echo.html) and both have occurred as defaults on R platforms: portable applications should use neither -n (as the first argument) nor escape sequences. The recommended replacement for echo -n is the command printf. Another common issue is the construction\nexport FOO=value\nwhich is bash-specific (first set the variable then export it by name).\nUsing test -e (or [ -e ]) in shell scripts is not fully portable78: -f is normally what is intended. Flags -a and -o are nowadays declared obsolescent by POSIX and should not be used.\nUse of ‘brace expansion’, e.g.,\nrm -f src/*.{o,so,d}\nis not portable.\nThe -o flag for set in shell scripts is optional in POSIX and not supported on all the platforms R is used on.\nThe variable OSTYPE is shell-specific and its values are rather unpredictable and may include a version such as darwin19.0: uname is often what is intended (with common values Darwin, Linux and SunOS).\nOn macOS which shell /bin/sh invokes is user- and platform-dependent: it might be bash version 3.2, dash or zsh (for new accounts it is zsh, for accounts ported from Mojave or earlier it is usually bash).\nMake use of the abilities of your compilers to check the standards-conformance of your code. For example, gcc, clang and gfortran79 can be used with options -Wall -pedantic to alert you to potential problems. This is particularly important for C++, where g++ -Wall -pedantic will alert you to the use of some of the GNU extensions which fail to compile on most other C++ compilers. If R was not configured accordingly, one can achieve this via personal Makevars files. See section ‘Customizing package compilation’ in the ‘R Installation and Administration’ manual for more information.\nPortable C++ code needs to follow both the 2011, 2014 and 2017 standards or to specify C+11/14/17/20 where available (which is not the case on all R platforms). Currently C++20 support is patchy across R platforms.\nIf using Fortran with the GNU compiler, use the flags -std=f95 -Wall -pedantic which reject most GNU extensions and features from later standards. (Although R only requires Fortran 90, gfortran does not have a way to specify that standard.) Also consider -std=f2008 as some recent compilers have Fortran 2008 or even 2018 as the minimum supported standard.\nNot all common R platforms conform to the expected standards, e.g. C99 for C code. One common area of problems is the *printf functions where Windows did not support %lld, %Lf and similar formats (and has its own formats such as %I64d for 64-bit integers). It is very rare to need to output such types, and 64-bit integers can usually be converted to doubles for output. However, the C11 standard (section 7.8.1) includes PRIxNN macros80 in C header inttypes.h (for example PRId64) so the portable approach is to test for these and if not available provide emulations in the package.\nAs from macOS 11 (late 2020), its C compiler sets the flag -Werror=implicit-function-declaration by default which forces stricter conformance to C99. This can be used on other platforms with gcc or clang. If your package has a (autoconf-generated) configure script, try installing it whilst using this flag, and read through the config.log file — compilation warnings and errors can lead to features which are present not being detected. (If possible do this on several platforms.)\nR CMD check performs some checks for non-portable compiler/linker flags in src/Makevars. However, it cannot check the meaning of such flags, and some are commonly accepted but with compiler-specific meanings. There are other non-portable flags which are not checked, nor are src/Makefile files and makefiles in sub-directories. As a comment in the code says\n\nIt is hard to think of anything apart from -I* and -D* that is safe for general use …\n\nalthough -pthread is pretty close to portable. (Option -U is portable but little use on the command line as it will only cancel built-in defines (not portable) and those defined earlier on the command line (R does not use any).)\nPeople have used configure to customize src/Makevars, including for specific compilers. This is unsafe for several reasons. First, unintended compilers might meet the check—for example, several compilers other than GCC identify themselves as ‘GCC’ whilst being only partially conformant. Second, future versions of compilers may behave differently (including updates to quite old series) so for example -Werror (and specializations) can make a package non-installable under a future version. Third, using flags to suppress diagnostic messages can hide important information for debugging on a platform not tested by the package maintainer. (R CMD check can optionally report on unsafe flags which were used.)\nAvoid the use of -march and especially -march=native. This allows the compiler to generate code that will only run on a particular class of CPUs (that of the compiling machine for native). People assume this is a ‘minimum’ CPU specification, but that is not how it is documented for gcc (it is accepted by clang but apparently it is undocumented what precisely it does, and it can be accepted and may be ignored for other compilers). (For personal use -mtune is safer, but still not portable enough to be used in a public package.) Not even gcc supports native for all CPUs, and it can do surprising things if it finds a CPU released later than its version.\nDo be very careful with passing arguments between R, C and Fortran code. In particular, long in C will be 32-bit on some R platforms (including 64-bit Windows), but 64-bit on most modern Unix and Linux platforms. It is rather unlikely that the use of long in C code has been thought through: if you need a longer type than int you should use a configure test for a C99/C++11 type such as int_fast64_t (and failing that, long long) and typedef your own type, or use another suitable type (such as size_t, but beware that is unsigned and ssize_t is not portable).\nIt is not safe to assume that long and pointer types are the same size, and they are not on 64-bit Windows. If you need to convert pointers to and from integers use the C99/C++11 integer types intptr_t and uintptr_t (in the headers <stdint.h> and <cstdint>: they are not required to be implemented by the standards but are used in C code by R itself).\nNote that integer in Fortran corresponds to int in C on all R platforms.\nUnder no circumstances should your compiled code ever call abort or exit81: these terminate the user’s R process, quite possibly losing all unsaved work. One usage that could call abort is the assert macro in C or C++ functions, which should never be active in production code. The normal way to ensure that is to define the macro NDEBUG, and R CMD INSTALL does so as part of the compilation flags. Beware of including headers (including from other packages) which could undefine it, now or in future versions. If you wish to use assert during development. you can include -UNDEBUG in PKG_CPPFLAGS or #undef it in your headers or code files. Note that your own src/Makefile or makefiles in sub-directories may also need to define NDEBUG.\nThis applies not only to your own code but to any external software you compile in or link to.\nCompiled code should not write to stdout or stderr and C++ and Fortran I/O should not be used. As with the previous item such calls may come from external software and may never be called, but package authors are often mistaken about that.\nCompiled code should not call the system random number generators such as rand, drand48 and random82, but rather use the interfaces to R’s RNGs described in Random number generation. In particular, if more than one package initializes a system RNG (e.g. via srand), they will interfere with each other. This applies also to Fortran 90’s random_number and random_seed, and Fortran 2018’s random_init. And to GNU Fortran’s rand, irand and srand. Except for drand48, what PRNG these functions use is implementation-dependent.\nNor should the C++11 random number library be used nor any other third-party random number generators such as those in GSL.\nUse of sprintf and vsprintf is regarded as a potential security risk and warned about on some platforms.83 R CMD check reports if any calls are found.\nErrors in memory allocation and reading/writing outside arrays are very common causes of crashes (e.g., segfaults) on some machines. See Checking memory access for tools which can be used to look for this.\nMany platforms will allow unsatisfied entry points in compiled code, but will crash the application (here R) if they are ever used. Some (notably Windows) will not. Looking at the output of\nnm -pg mypkg.so\nand checking if any of the symbols marked U is unexpected is a good way to avoid this.\nLinkers have a lot of freedom in how to resolve entry points in dynamically-loaded code, so the results may differ by platform. One area that has caused grief is packages including copies of standard system software such as libz (especially those already linked into R). In the case in point, entry point gzgets was sometimes resolved against the old version compiled into the package, sometimes against the copy compiled into R and sometimes against the system dynamic library. The only safe solution is to rename the entry points in the copy in the package. We have even seen problems with entry point name myprintf, which is a system entry point84 on some Linux systems.\nA related issue is the naming of libraries built as part of the package installation. macOS and Windows have case-insensitive file systems, so using\n-L. -lLZ4\nin PKG_LIBS will match liblz4. And -L. only appends to the list of searched locations, and liblz4 might be found in an earlier-searched location (and has been). The only safe way is to give an explicit path, for example\n./libLZ4.a\nConflicts between symbols in DLLs are handled in very platform-specific ways. Good ways to avoid trouble are to make as many symbols as possible static (check with nm -pg), and to use names which are clearly tied to your package (which also helps users if anything does go wrong). Note that symbol names starting with R_ are regarded as part of R’s namespace and should not be used in packages.\nIt is good practice for DLLs to register their symbols (see Registering native routines), restrict visibility (see Controlling visibility) and not allow symbol search (see Registering native routines). It should be possible for a DLL to have only one visible symbol, R_init_pkgname, on suitable platforms85, which would completely avoid symbol conflicts.\nIt is not portable to call compiled code in R or other packages via .Internal, .C, .Fortran, .Call or .External, since such interfaces are subject to change without notice and will probably result in your code terminating the R process.\nDo not use (hard or symbolic) file links in your package sources. Where possible R CMD build will replace them by copies.\nIf you do not yourself have a Windows system, consider submitting your source package to WinBuilder (https://win-builder.r-project.org/) before distribution. If you need to check on an M1 Mac, there is a check service at https://mac.r-project.org/macbuilder/submit.html.\nIt is bad practice for package code to alter the search path using library, require or attach and this often does not work as intended. For alternatives, see Suggested packages and with().\nExamples can be run interactively via example as well as in batch mode when checking. So they should behave appropriately in both scenarios, conditioning by interactive() the parts which need an operator or observer. For instance, progress bars86 are only appropriate in interactive use, as is displaying help pages or calling View() (see below).\nBe careful with the order of entries in macros such as PKG_LIBS. Some linkers will re-order the entries, and behaviour can differ between dynamic and static libraries. Generally -L options should precede87 the libraries (typically specified by -l options) to be found from those directories, and libraries are searched once in the order they are specified. Not all linkers allow a space after -L .\nCare is needed with the use of LinkingTo. This puts one or more directories on the include search path ahead of system headers but (prior to R 3.4.0) after those specified in the CPPFLAGS macro of the R build (which normally includes -I/usr/local/include, but most platforms ignore that and include it with the system headers).\nAny confusion would be avoided by having LinkingTo headers in a directory named after the package. In any case, name conflicts of headers and directories under package include directories should be avoided, both between packages and between a package and system and third-party software.\nThe ar utility is often used in makefiles to make static libraries. Its modifier u is defined by POSIX but is disabled in GNU ar on some Linux distributions which use ‘deterministic mode’. The safest way to make a static library is to first remove any existing file of that name then use ar -cr and then ranlib if needed (which is system-dependent: on most systems88 ar always maintains a symbol table). The POSIX standard says options should be preceded by a hyphen (as in -cr), although most OSes accept them without. Note that on some systems ar -cr must have at least one file specified.\nThe s modifier (to replace a separate call to ranlib) is required by X/OPEN but not POSIX, so ar -crs is not portable.\nThe strip utility is platform-specific (and CRAN prohibits removing debug symbols). For example the options --strip-debug and --strip-unneeded of the GNU version are not supported on macOS: the POSIX standard for strip does not mention any options, and what calling it without options does is platform-dependent. Stripping a .so file could even prevent it being dynamically loaded into R on an untested platform.\nld -S invokes strip --strip-debug for GNU ld (and similarly on macOS) but is not portable: in particular on Solaris it did something completely different and took an argument.\nSome people have a need to set a locale. Locale names are not portable, and e.g. fr_FR.utf8 is commonly used on Linux but not accepted on macOS. fr_FR.UTF-8 is more portable, being accepted on recent Linux, AIX, FreeBSD, macOS and Solaris (at least). However, some Linux distributions micro-package, so locales defined by glibc (including these examples) may not be installed.\nAvoid spaces in file names, not least as they can cause difficulties for external tools. An example was a package with a knitr vignette that used spaces in plot names: this caused some older versions of pandoc to fail with a baffling error message.\nNon-ASCII filenames can also cause problems (particularly in non-UTF-8 locales).\nTake care in naming LaTeX macros (also known as ‘commands’) in vignette sources: if these are also defined in a future version of one of the LaTeX packages used there will be a fatal error. One instance in 2021 was package hyperref newly defining \\C, \\F, \\G, \\U and \\textapprox. If you are confident that your definitions will be the only ones relevant you can use \\renewcommand but it is better to use names clearly associated with your package.\nMake sure that any version requirement for Java code is both declared in the SystemRequirements field89 and tested at runtime (not least as the Java installation when the package is installed might not be the same as when the package is run and will not be for binary packages).\nWhen specifying a minimum Java version please use the official version names, which are (confusingly)\n1.1 1.2 1.3 1.4 5.0 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21\nand as from 2018 a year.month scheme such as 18.9 is also in use. Fortunately only the integer values are likely to be relevant. If at all possible, use one of the LTS versions (8, 11, 17, 21 …) as the minimum version. The preferred form of version specification is\nSystemRequirements: Java (>= 11)\nA suitable test for Java at least version 8 for packages using rJava would be something like\n.jinit()\njv <- .jcall(\"java/lang/System\", \"S\", \"getProperty\", \"java.runtime.version\")\nif(substr(jv, 1L, 2L) == \"1.\") {\n jvn <- as.numeric(paste0(strsplit(jv, \"[.]\")[[1L]][1:2], collapse = \".\"))\n if(jvn < 1.8) stop(\"Java >= 8 is needed for this package but not available\")\n}\nJava 9 changed the format of this string (which used to be something like 1.8.0_292-b10); Java 11 gave jv as 11+28 whereas Java 11.0.11 gave 11.0.11+9. (https://openjdk.org:443/jeps/322 details the current scheme. Note that it is necessary to allow for pre-releases like 11-ea+22.)\nNote too that the compiler used to produce a jar can impose a minimum Java version, often resulting in an arcane message like\njava.lang.UnsupportedClassVersionError: ... Unsupported major.minor version 52.0\n(Where https://en.wikipedia.org/wiki/Java_class_file maps class-file version numbers to Java versions.) Compile with something like javac -target 11 to ensure this is avoided. Note this also applies to packages distributing (or even downloading) compiled Java code produced by others, so their requirements need to be checked (they are often not documented accurately) and accounted for. It should be possible to check the class-file version via command-line utility javap, if necessary after extracting the .class files from a .jar archive. For example,\njar xvf some.jar\njavap -verbose path/to/some.class | grep major\nSome packages have stated a requirement on a particular JDK, but a package should only be requiring a JRE unless providing its own Java interface.\nJava 8 is still in widespread use (and may remain so because of licence changes and support on older OSes: OpenJDK has security support until March 2026). On the other hand, newer platforms may only have support for recent versions of Java: for arm64 macOS the first officially supported version was\n\n\n\nA package with a hard-to-satisfy system requirement is by definition not portable, annoyingly so if this is not declared in the SystemRequirements field. The most common example is the use of pandoc, which is only available for a very limited range of platforms (and has onerous requirements to install from source) and has capabilities90 that vary by build but are not documented. Several recent versions of pandoc for macOS did not work on R’s then target of High Sierra (and this too was undocumented). Another example is the Rust compilation system (cargo and rustc).\nUsage of external commands should always be conditional on a test for presence (perhaps using Sys.which), as well as declared in the SystemRequirements field. A package should pass its checks without warnings nor errors without the external command being present.\nAn external command can be a (possibly optional) requirement for an imported or suggested package but needed for examples, tests or vignettes in the package itself. Such usages should always be declared and conditional.\nInterpreters for scripting languages such as Perl, Python and Ruby need to be declared as system requirements and used conditionally: for example macOS 10.16 was announced not to have them (but released as macOS 11 with them); later it was announced that macOS 12.3 does not have Python 2 and only a minimal install of Python 3 is included. Python 2 has passed end-of-life and been removed from many major distributions. Support for Rust or Go cannot be assumed.\nCommand cmake is not commonly installed, and where it is, it might not be on the path. In particular, the most common location on macOS is /Applications/CMake.app/Contents/bin/cmake and that should be looked for if cmake is not found on the path.\nBe sure to use portable encoding names: none of utf8, mac and macroman is portable. See the help for file for more details.\nDo not invoke R by plain R, Rscript or (on Windows) Rterm in your examples, tests, vignettes, makefiles or other scripts. As pointed out in several places earlier in this manual, use something like\n\"$(R_HOME)/bin/Rscript\"\n\"$(R_HOME)/bin$(R_ARCH_BIN)/Rterm\"\nwith appropriate quotes (as, although not recommended, R_HOME can contain spaces).\nDo not use R_HOME in makefiles except when passing them to the shell. Specifically, do not use R_HOME in the argument to include, as R_HOME can contain spaces. Quoting the argument to include does not help. A portable and the recommended way to avoid the problem of spaces in ${R_HOME} is using option -f of make. This is easy to do with recursive invocation of make, which is also the only usual situation when R_HOME is needed in the argument for include. makefile $(MAKE) -f \"${R_HOME}/etc${R_ARCH}/Makeconf\" -f Makefile.inner\nIf distributing datasets involving date-times, consider if a time zone needs to be specified. The most portable way to distribute date-times is as objects of class \"POSIXct\" and as these record the time in UTC, the time represented is independent of the time zone: but how it is printed may not be. Objects of class \"POSIXlt\" should have a \"tzone\" attribute. Dates (e.g, birthdays) are conventionally considered independently of time zone.\nIf at all possible avoid any Internet access during package installation. Installation and use may well be on different machines/accounts and those allowed to install software may have no Internet access, and being self-contained helps ensure long-term reproducibility.\n\n73 Solaris make did not accept CRLF-terminated Makefiles; Solaris warned about and some other makes ignore incomplete final lines.74 This was apparently introduced in SunOS 4, and is available elsewhere provided it is surrounded by spaces.75 GNU make, BSD make and other variants of pmake in FreeBSD, NetBSD and formerly in macOS, and formerly AT&T make as implemented on Solaris and ‘Distributed Make’ (dmake), part of Oracle Developer Studio and available in other versions including from Apache OpenOffice.76 For example, test options -a and -e are not portable, and not supported in the AT&T Bourne shell used on Solaris 10/11, even though they are in the POSIX standard. Nor did Solaris support $(cmd).77 as from R 4.0.0 the default is bash.78 it was not in the Bourne shell, and was not supported by Solaris 10.79 https://fortranwiki.org/fortran/show/Modernizing+Old+Fortran may help explain some of the warnings from gfortran -Wall -pedantic.80 These are optional because the corresponding types are, but must be provided if the types are.81 or where supported the variants _Exit and _exit.82 This and srandom are in any case not portable. They are in POSIX but not in the C99 standard, and not available on Windows.83 including macOS as from version 13.84 in libselinux.85 At least Linux and Windows, but not macOS.86 except perhaps the simplest kind as used by download.file() in non-interactive use.87 Whereas the GNU linker reorders so -L options are processed first, the Solaris one did not.88 some versions of macOS did not.89 If a Java interpreter is required directly (not via rJava) this must be declared and its presence tested like any other external command.90 For example, the ability to handle https:// URLs.Do be careful in what your tests (and examples) actually test. Bad practice seen in distributed packages include:\n\nIt is not reasonable to test the time taken by a command: you cannot know how fast or how heavily loaded an R platform might be. At best you can test a ratio of times, and even that is fraught with difficulties and not advisable: for example, the garbage collector may trigger at unpredictable times following heuristics that may change without notice.\nDo not test the exact format of R messages (from R itself or from other packages): They change, and they can be translated.\nPackages have even tested the exact format of system error messages, which are platform-dependent and perhaps locale-dependent. For example, in late 2021 libcurl changed its warning/error messages, including when URLs are not found.\nIf you use functions such as View, remember that in testing there is no one to look at the output. It is better to use something like one of\nif(interactive()) View(obj) else print(head(obj))\nif(interactive()) View(obj) else str(obj)\nBe careful when comparing file paths. There can be multiple paths to a single file, and some of these can be very long character strings. If possible canonicalize paths before comparisons, but study ?normalizePath to be aware of the pitfalls.\nOnly test the accuracy of results if you have done a formal error analysis. Things such as checking that probabilities numerically sum to one are silly: numerical tests should always have a tolerance. That the tests on your platform achieve a particular tolerance says little about other platforms. R is configured by default to make use of long doubles where available, but they may not be available or be too slow for routine use. Most R platforms use ix86 or x86_64 CPUs: these may use extended precision registers on some but not all of their FPU instructions. Thus the achieved precision can depend on the compiler version and optimization flags—our experience is that 32-bit builds tend to be less precise than 64-bit ones. But not all platforms use those CPUs, and not all91 which use them configure them to allow the use of extended precision. In particular, current ARM CPUs do not have extended precision nor long doubles, and clang currently has long double the same as double on all ARM CPUs. On the other hand some CPUs have higher-precision modes which may be used for long double, notably 64-bit PowerPC and Sparc.\nIf you must try to establish a tolerance empirically, configure and build R with --disable-long-double and use appropriate compiler flags (such as -ffloat-store and -fexcess-precision=standard for gcc, depending on the CPU type92) to mitigate the effects of extended-precision calculations. The platform most often seen to give different numerical results is arm64 macOS, so be sure to include that in any empirical determination.\nTests which involve random inputs or non-deterministic algorithms should normally set a seed or be tested for many seeds.\nTests should use options(warn = 1) as reporting\nThere were 22 warnings (use warnings() to see them)\nis pointless, especially for automated checking systems.\nIf your package uses dates/times, ensure that it works in all timezones, especially those near boundaries (problems have most often be seen in Europe/London (zero offset in Winter) and Pacific/Auckland, near enough the International Date line) and with offsets not in whole hours (Adelaide, Chatham Islands, …). More extreme examples are Africa/Conakry (permanent UTC), Asia/Calcutta (no DST, permanent half-hour offset) and Pacific/Kiritimati(no DST, more than 12 hours ahead of UTC).\n\n91 Not doing so is the default on Windows, overridden for the R executables.92 These are not needed for the default compiler settings on x86_64 but are likely to be needed on ix86.\n1.6.1 PDF size\nThere are a several tools available to reduce the size of PDF files: often the size can be reduced substantially with no or minimal loss in quality. Not only do large files take up space: they can stress the PDF viewer and take many minutes to print (if they can be printed at all).\nqpdf (https://qpdf.sourceforge.io/) can compress losslessly. It is fairly readily available (e.g. it has binaries for Windows and packages in Debian/Ubuntu/Fedora, and is installed as part of the CRAN macOS distribution of R). R CMD build has an option to run qpdf over PDF files under inst/doc and replace them if at least 10Kb and 10% is saved. The full path to the qpdf command can be supplied as environment variable R_QPDF (and is on the CRAN binary of R for macOS). It seems MiKTeX does not use PDF object compression and so qpdf can reduce considerably the sizes of files it outputs: MiKTeX’s defaults can be overridden by code in the preamble of an Sweave or LaTeX file — see how this is done for the R reference manual at https://svn.r-project.org/R/trunk/doc/manual/refman.top.\nOther tools can reduce the size of PDFs containing bitmap images at excessively high resolution. These are often best re-generated (for example Sweave defaults to 300 ppi, and 100–150 is more appropriate for a package manual). These tools include Adobe Acrobat (not Reader), Apple’s Preview93 and Ghostscript (which converts PDF to PDF by93 Select ‘Save as’, and select ‘Reduce file size’ from the ‘Quartz filter’ menu’: this can be accessed in other ways, for example by Automator.\nps2pdf options -dAutoRotatePages=/None -dPrinted=false in.pdf out.pdf\nand suitable options might be\n-dPDFSETTINGS=/ebook\n-dPDFSETTINGS=/screen\nSee https://ghostscript.readthedocs.io/en/latest/VectorDevices.html for more such and consider all the options for image downsampling). There have been examples in CRAN packages for which current versions of Ghostscript produced much bigger reductions than earlier ones (e.g. at the upgrades from 9.50 to 9.52, from 9.55 to 9.56 and then to 10.00.0).\nWe come across occasionally large PDF files containing excessively complicated figures using PDF vector graphics: such figures are often best redesigned or failing that, output as PNG files.\nOption --compact-vignettes to R CMD build defaults to value qpdf: use both to try harder to reduce the size, provided you have Ghostscript available (see the help for tools::compactPDF).\n\n\n1.6.2 Check timing\nThere are several ways to find out where time is being spent in the check process. Start by setting the environment variable _R_CHECK_TIMINGS_ to 0. This will report the total CPU times (not Windows) and elapsed times for installation and running examples, tests and vignettes, under each sub-architecture if appropriate. For tests and vignettes, it reports the time for each as well as the total.\nSetting _R_CHECK_TIMINGS_ to a positive value sets a threshold (in seconds elapsed time) for reporting timings.\nIf you need to look in more detail at the timings for examples, use option --timings to R CMD check (this is set by --as-cran). This adds a summary to the check output for all the examples with CPU or elapsed time of more than 5 seconds. It produces a file mypkg.Rcheck/mypkg-Ex.timings containing timings for each help file: it is a tab-delimited file which can be read into R for further analysis.\nTimings for the tests and vignette runs are given at the bottom of the corresponding log file: note that log files for successful vignette runs are only retained if environment variable _R_CHECK_ALWAYS_LOG_VIGNETTE_OUTPUT_ is set to a true value.\n\n\n1.6.3 Encoding issues\nThe issues in this subsection have been much alleviated by the change in R 4.2.0 to running the Windows port of R in a UTF-8 locale where available. However, Windows users might be running an earlier version of R on an earlier version of Windows which does not support UTF-8 locales.\nCare is needed if your package contains non-ASCII text, and in particular if it is intended to be used in more than one locale. It is possible to mark the encoding used in the DESCRIPTION file and in .Rd files, as discussed elsewhere in this manual.\nFirst, consider carefully if you really need non-ASCII text. Some users of R will only be able to view correctly text in their native language group (e.g. Western European, Eastern European, Simplified Chinese) and ASCII.94. Other characters may not be rendered at all, rendered incorrectly, or cause your R code to give an error. For .Rd documentation, marking the encoding and including ASCII transliterations is likely to do a reasonable job. The set of characters which is commonly supported is wider than it used to be around 2000, but non-Latin alphabets (Greek, Russian, Georgian, …) are still often problematic and those with double-width characters (Chinese, Japanese, Korean, emoji) often need specialist fonts to render correctly.94 except perhaps some special characters such as backslash and hash which may be taken over for currency symbols.\nSeveral CRAN packages have messages in their R code in French (and a few in German). A better way to tackle this is to use the internationalization facilities discussed elsewhere in this manual.\nFunction showNonASCIIfile in package tools can help in finding non-ASCII bytes in files.\nThere is a portable way to have arbitrary text in character strings (only) in your R code, which is to supply them in Unicode as \\uxxxx escapes (or, rarely needed except for emojis, \\Uxxxxxxxx escapes). If there are any characters not in the current encoding the parser will encode the character string as UTF-8 and mark it as such. This applies also to character strings in datasets: they can be prepared using \\uxxxx escapes or encoded in UTF-8 in a UTF-8 locale, or even converted to UTF-8 via iconv(). If you do this, make sure you have R (>= 2.10) (or later) in the Depends field of the DESCRIPTION file.\nR sessions running in non-UTF-8 locales will if possible re-encode such strings for display (and this is done by RGui on older versions of Windows, for example). Suitable fonts will need to be selected or made available95 both for the console/terminal and graphics devices such as X11() and windows(). Using postscript or pdf will choose a default 8-bit encoding depending on the language of the UTF-8 locale, and your users would need to be told how to select the encoding argument.95 Typically on a Unix-alike this is done by telling fontconfig where to find suitable fonts to select glyphs from.\nNote that the previous two paragraphs only apply to character strings in R code. Non-ASCII characters are particularly prevalent in comments (in the R code of the package, in examples, tests, vignettes and even in the NAMESPACE file) but should be avoided there. Most commonly people use the Windows extensions to Latin-1 (often directional single and double quotes, ellipsis, bullet and en and em dashes) which are not supported in strict Latin-1 locales nor in CJK locales on Windows. A surprisingly common misuse is to use a right quote in don't instead of the correct apostrophe.\nDatasets can include marked UTF-8 or Latin-1 character strings. As R is nowadays unlikely to be run in a Latin-1 or Windows’ CP1252 locale, for performance reasons these should be converted to UTF-8.\nIf you want to run R CMD check on a Unix-alike over a package that sets a package encoding in its DESCRIPTION file and do not use a UTF-8 locale you may need to specify a suitable locale via environment variable R_ENCODING_LOCALES. The default is equivalent to the value\n\"latin1=en_US:latin2=pl_PL:UTF-8=en_US.UTF-8:latin9=fr_FR.iso885915@euro\"\n(which is appropriate for a system based on glibc: macOS requires latin9=fr_FR.ISO8859-15) except that if the current locale is UTF-8 then the package code is translated to UTF-8 for syntax checking, so it is strongly recommended to check in a UTF-8 locale.\n\n\n1.6.4 Portable C and C++ code\nWriting portable C and C++ code is mainly a matter of observing the standards (C99, C++14 or where declared C++11/17/20) and testing that extensions (such as POSIX functions) are supported. Do make maximal use of your compiler diagnostics — this typically means using flags -Wall and -pedantic for both C and C++ and additionally -Werror=implicit-function-declaration and -Wstrict-prototypes for C (on some platforms and compiler versions) these are part of -Wall or -pedantic).\nC++ standards: From version 3.6.0 (3.6.2 on Windows), R defaulted to C++11 where available96; from R 4.1.0 to C++14 and from R 4.3.0 to C++17 (where available). However, in earlier versions the default standard was that of the compiler used, often C++98 or C++14, and the default is likely to change in future. For maximal portability a package should either specify a standard (see Using C++ code) or be tested under all of C++11, C++98, C++14 and C++17. (Specifying C++14 or later will limit portability.)96 which it is on all known platforms, and is required as from R 4.0.0\nNote that the ‘TR1’ C++ extensions are not part of any of these standards and the <tr1/name> headers are not supplied by some of the compilers used for R, including on macOS. (Use the C++11 versions instead.)\nA common error is to assume recent versions of compilers or OSes. In production environments ‘long term support’ versions of OSes may be in use for many years,97 and their compilers may not be updated during that time. For example, GCC 4.8 was still in use in 2022 and could be (in RHEL 7) until 2028: that supports neither C++14 nor C++17.97 Ubuntu provides 5 years of support (but people were running 14.04 after 7 years) and RHEL provides 10 years full support and up to 14 with extended support.\nThe POSIX standards only require recently-defined functions to be declared if certain macros are defined with large enough values, and on some compiler/OS combinations98 they are not declared otherwise. So you may need to include something like one of98 This is seen on Linux, Solaris and FreeBSD, although each has other ways to turn on all extensions, e.g. defining _GNU_SOURCE, __EXTENSIONS__ or _BSD_SOURCE: the GCC compilers by default define _GNU_SOURCE unless a strict standard such as -std=c99 is used. On macOS extensions are declared unless one of these macros is given too small a value.\n#define _XOPEN_SOURCE 600\nor\n#ifdef __GLIBC__\n# define _POSIX_C_SOURCE 200809L\n#endif\nbefore any headers. (strdup, strncasecmp and strnlen are such functions – there were several older platforms which did not have the POSIX 2008 function strnlen.)\nHowever, some common errors are worth pointing out here. It can be helpful to look up functions at https://cplusplus.com/reference/ or https://en.cppreference.com/w/ and compare what is defined in the various standards.\nMore care is needed for functions such as mallinfo which are not specified by any of these standards—hopefully the man page on your system will tell you so. Searching online for such pages for various OSes (preferably at least Linux and macOS, and the FreeBSD manual pages at https://man.freebsd.org/cgi/man.cgi allow you to select many OSes) should reveal useful information but a configure script is likely to be needed to check availability and functionality.\nBoth the compiler and OS (via system header files, which may differ by architecture even for nominally the same OS) affect the compilability of C/C++ code. Compilers from the GCC, LLVM (clang and flang) Intel and Oracle Developer Studio suites have been used with R, and both LLVM clang and Oracle have more than one implementation of C++ headers and library. The range of possibilities makes comprehensive empirical checking impossible, and regrettably compilers are patchy at best on warning about non-standard code.\n\nMathematical functions such as sqrt are defined in C++11 for floating-point arguments: float, double, long double and possibly more. The standard specifies what happens with an argument of integer type but this is not always implemented, resulting in a report of ‘overloading ambiguity’: this was commonly seen on Solaris, but for pow also seen on macOS and other platforms using clang++.\nA not-uncommonly-seen problem is to mistakenly call floor(x/y) or ceil(x/y) for int arguments x and y. Since x/y does integer division, the result is of type int and ‘overloading ambiguity’ may be reported. Some people have (pointlessly) called floor and ceil on arguments of integer type, which may have an ‘overloading ambiguity’.\nA surprising common misuse is things like pow(10, -3): this should be the constant 1e-3. Note that there are constants such as M_SQRT2 defined via Rmath.h99 for sqrt(2.0), frequently mis-coded as sqrt(2).\nFunction fabs is defined only for floating-point types, except in C++11 and later which have overloads for std::fabs in <cmath> for integer types. Function abs is defined in C99’s <stdlib.h> for int and in C++’s <cstdlib> for integer types, overloaded in <cmath> for floating-point types. C++11 has additional overloads for std::abs in <cmath> for integer types. The effect of calling abs with a floating-point type is implementation-specific: it may truncate to an integer. For clarity and to avoid compiler warnings, use abs for integer types and fabs for double values, and when using C++ include <cmath> and use the std:: prefix.\nIt is an error (and make little sense, although has been seen) to call macros/functions isnan, isinf and isfinite for integer arguments: a few compilers give a compilation error. Function finite is obsolete, and some compilers will warn about its use100.\nThe GNU C/C++ compilers support a large number of non-portable extensions. For example, INFINITY (which is a float value in C99 and C++11), for which R provides the portable double value R_PosInf (and R_NegInf for -INFINITY). And NAN101 is just one NaN float value: for use with R, NA_REAL is often what is intended, but R_NaN is also available.\nSome (but not all) extensions are listed at https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html and https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Extensions.html.\nOther GNU extensions which have bitten package writers are the use of non-portable characters such as $ in identifiers and use of C++ headers under ext.\nitem Including C-style headers in C++ code is not portable. Including the legacy header102 math.h in C++ code may conflict with cmath which may be included by other headers. In C++11, functions like sqrt and isnan are defined for double arguments in math.h and for a range of types including double in cmath. Similar issues have been seen for stdlib.h and cstdlib. Including the C++ header first used to be a sufficient workaround but for some 2016 compilers only one could be included.\nBe careful to include the headers which define the functions you use. Some compilers/OSes include other system headers in their headers which are not required by the standards, and so code may compile on such systems and not on others. (A prominent example is the C++ header <random> which is indirectly included by <algorithm> by g++. Another issue is the C header <time.h> which is included by other headers on Linux and Windows but not macOS.) g++ 11 often needs explicit inclusion of the C++ headers <limits> (for numeric_limits) or <exception> (for set_terminate and similar), whereas earlier versions included these in other headers. g++ 13 requires the explicit inclusion of <cstdint> for types such as uint32_t which was previously included implicitly. (For more such, see https://gcc.gnu.org/gcc-13/porting_to.html.)\nNote that malloc, calloc, realloc and free are defined by C99 in the header stdlib.h and (in the std:: namespace) by C++ header cstdlib. Some earlier implementations used a header malloc.h, but that is not portable and does not exist on macOS.\nThis also applies to types such as ssize_t. The POSIX standards say that is declared in headers unistd.h and sys/types.h, and the latter is often included indirectly by other headers on some but not all systems.\nSimilarly for constants: for example SIZE_MAX is defined in stdint.h alongside size_t.\nSome headers are not portable: we have just mentioned malloc.h and often CRAN submissions attempt to use endian.h. The latter is a glibc extension: some OSs have machine/endian.h or sys/endian.h but some have neither.\nUse #include \"my.h\" not #include <my.h> for headers in your package. The second form is intended for system headers and the search order for such headers is platform-dependent (and may not include the current directory). For extra safety, name headers in a way that cannot be confused with a system header so not, for example, types.h.\nFor C++ code, be careful to specify namespaces where needed. Many functions are defined by the standards to be in the std namespace, but g++ puts many such also in the C++ main namespace. One way to do so is to use declarations such as\nusing std::floor;\nbut it is usually preferable to use explicit namespace prefixes in the code.\nExamples seen in CRAN packages include\nabs acos atan bind calloc ceil div exp fabs floor fmod free log malloc\nmemcpy memset pow printf qsort round sin sprintf sqrt strcmp strcpy\nstrerror strlen strncmp strtol tan trunc\nThis problem is less common than it used to be, but in 2019 LLVM clang did not have bind in the main namespace. Also seen has been type size_t defined only in the std namespace.\nNB: These functions are only guaranteed to be in the std namespace if the correct C++ header is included, e.g. <cmath> rather than <math.h>.\nIf you define functions in C++ which are inspired by later standards, put them in a namespace and refer to them using the namespace. We have seen conflicts with std::make_unique from C++14 and std::byte, std::data, std::sample and std::size from C++17.\nIn C++ code\nusing namesapace std; \nis not good practice, and has caused platform-dependent errors if included before headers, especially system headers (which may be included by other headers). The best practice is to use explicit std:: prefixes for all functions declared by the C++ standard to be in that namespace.\nSome C++ compilers refuse to compile constructs such as\n if(ptr > 0) { ....}\nwhich compares a pointer to the integer 0. This could just use if(ptr) (pointer addresses cannot be negative) but if needed pointers can be tested against nullptr (C++11) or NULL.\nMacros defined by the compiler/OS can cause problems. Identifiers starting with an underscore followed by an upper-case letter or another underscore are reserved for system macros and should not be used in portable code (including not as guards in C/C++ headers). Other macros, typically upper-case, may be defined by the compiler or system headers and can cause problems. Some of these can be avoided by defining _POSIX_C_SOURCE before including any system headers, but it is better to only use all-upper-case names which have a unique prefix such as the package name.\ntypedefs in OS headers can conflict with those in the package: examples have included ulong, index_t, single and thread. (Note that these may conflict with other uses as identifiers, e.g. defining a C++ function called single.) The POSIX standard reserves (in §2.2.2) all identifiers ending in _t.\nSome compilers do not allow a space between -D and the macro to be defined. Similarly for -U.\nIf you use OpenMP, check carefully that you have followed the advice in the subsection on OpenMP support. In particular, any use of OpenMP in C/C++ code will need to use\n#ifdef _OPENMP\n# include <omp.h>\n#endif\nAny use of OpenMP functions, e.g. omp_set_num_threads, also needs to be conditioned. To avoid incessant warnings such as\nwarning: ignoring #pragma omp parallel [-Wunknown-pragmas]\nuses of such pragmas should also be conditioned (or commented out if they are used in code in a package not enabling OpenMP on any platform).\nDo not hardcode -lgomp: not only is that specific to the GCC family of compilers, using the correct linker flag often sets up the run-time path to the library.\nPackage authors commonly assume things are part of C/C++ when they are not: the most common example is POSIX103 function strdup. The most common C library on Linux, glibc, will hide the declarations of such extensions unless a ‘feature-test macro’ is defined before (almost) any system header is included. So for strdup you need\n#define _POSIX_C_SOURCE 200809L\n...\n#include <string.h>\n...\nstrdup call(s)\nwhere the appropriate value can be found by man strdup on Linux. (Use of strncasecmp is similar.)\nHowever, modes of gcc with ‘GNU EXTENSIONS’ (which are the default, either -std=gnu99 or -std=gnu11) declare enough macros to ensure that missing declarations are rarely seen.\nThis applies also to constants such as M_PI and M_LN2, which are part of the X/Open standard: to use these define _XOPEN_SOURCE before including any headers, or include the R header Rmath.h.\nUsing alloca portably is tricky: it is neither an ISO C/C++ nor a POSIX function. An adequately portable preamble is\n#ifdef __GNUC__\n/* Includes GCC, clang and Intel compilers */\n# undef alloca\n# define alloca(x) __builtin_alloca((x))\n#elif defined(__sun) || defined(_AIX)\n/* this was necessary (and sufficient) for Solaris 10 and AIX 6: */\n# include <alloca.h>\n#endif\nCompiler writers feel free to implement features from later standards than the one specified, so for example they may implement or warn on C++14/17/20 features when C++11 is specified. Portable code will not use such features – it can be hard to know what they are but the most common warnings are\n'register' storage class specifier is deprecated and incompatible with C++17\n\nISO C++11 does not allow conversion from string literal to 'char *'\n(where conversion should be to const char *). Keyword register was not mentioned in C++98, deprecated in C++11 and removed in C++17.\nThere are quite a lot of other C++98 features deprecated in C++11 and removed in C++17, and LLVM clang 9 and later warn about them (and as from version 16 they have been removed). Examples include bind1st/bind2nd (use std::bind or lambdas104) std::auto_ptr (replaced by std::unique_ptr), std::mem_fun_ref and std::ptr_fun.\nLater versions of standards may add reserved words: for example bool, false and true became keywords in C23 and are no longer available as variable names. As noted above, C++17 uses byte, data, sample and size.\nSo avoid common words and keywords from other programming languages.\nBe careful about including C headers in C++ code. Issues include\n\nUse of the register storage class specifier (see the previous but one item).\nThe C99 keyword restrict is not part of105 any C++ standard and is rejected by some C++ compilers.\nInclusion by such headers of C-style headers such as math.h (see above).\n\nThe most portable way to interface to other software with a C API is to use C code (which can normally be mixed with C++ code in a package).\nreinterpret_cast in C++ is not safe for pointers: for example the types may have different alignment requirements. Use memcpy to copy the contents to a fresh variable of the destination type.\nAvoid platform-specific code if at all possible, but if you need to test for a platform ensure that all platforms are covered. For example, __unix__ is not defined on all Unix-alikes, in particular not on macOS. A reasonably portable way to condition code for a Unix-alike is\n#if defined (__unix__) || (defined (__APPLE__) && defined (__MACH__))\n#endif\nbut\n#ifdef _WIN32\n// Windows-specific code\n#else\n// Unix-alike code\n#endif\nwould be better. For a Unix-alike it is much better to use configure to test for the functionality needed than make assumptions about OSes (and people all too frequently forget R is used on platforms other than Linux, Windows and macOS — and some forget macOS).\nHeaders in subdirectories are often not portable. For C++, this includes bits/, tr1/ and tr2/, none of which exist on macOS (and ext/ exists there but with different content from g++-based platforms). Header bits/stdc++.h is both not portable and not recommended for end-user code even on platforms which include it.\nBe careful if using malloc or calloc. First, their return value must always be checked to see if the allocation succeeded – it is almost always easier to use R’s R_Calloc, which does check. Second, the first argument is of type size_t and recent compilers are warning about passing signed arguments (which could get promoted to ridiculously large values).\nFor C code, consider using the flag -Wstrict-prototypes which is supported by gcc and LLVM and Apple clang. This has found quite a number of errors where functions have been declared without arguments and is likely to become the default in future compilers. (It already is for LLVM clang in C23 mode.) Note that using f() for a function without any parameters was deprecated in C99 and C11, but it expected to be non-deprecated in C23. However, f(void) is supported by all standards and avoids any uncertainty.\nLLVM clang has a separate warning -Wdeprecated-non-prototype which is enabled by -Wstrict-prototypes. This warns on K&R-style usage, which will not be accepted in C23.\nSeveral C entry points are warned against in their man pages on most systems, often in very strong terms such as ‘Do not use these functions’. macOS has started to warn106 if these are used for sprintf, vsprintf, gets, mktemp, tempmam and tmpnam. It is highly recommended that you use safer alternatives (on any platform) but the warning can be avoided by defining _POSIX_C_SOURCE to for example 200809L before including the (C or C++) header which defines them. (However, this may hide other extensions.)\nCompilers may interpret comments in source code, so it is necessary to remove any intended for a compiler to interpret. The main example has been comments for Visual Fortran (as the Intel Fortran compiler has been known on Windows107) like\n!DEC$ ATTRIBUTES DLLEXPORT,C,REFERENCE,ALIAS:'kdenestmlcvb' :: kdenestmlcvb\nwhich are interpreted by Intel Fortran on all platforms (and are inappropriate for use with R on Windows). gfortran has similar forms starting with !GCC$.\nThe C++ new operator takes argument std::size_t size, which is unsigned. Using a signed integer type such as int may lead to compiler warnings such as\nwarning: argument 1 value '18446744073709551615' exceeds maximum object\n size 9223372036854775807 [-Walloc-size-larger-than=]\n(especially if LTO is used). So don’t do that!\n\n99 often taken from the toolchain’s headers.100 at the time of writing arm64 macOS both warned and did not supply a prototype in math.h which resulted in a compilation error.101 also part of C++11 and later.102 which often is the same as the header included by the C compiler, but some compilers have wrappers for some of the C headers.103 Although this is expected to be part of C23, full support of that is years away.104 https://stackoverflow.com/questions/32739018/a-replacement-for-stdbind2nd105 it is allowed but ignored in system headers.106 when using the macOS 13 SDK with a deployment target of macOS 13.107 and at one time as DEC Fortran, hence the DEC.Some additional information for C++ is available at https://journal.r-project.org/archive/2011-2/RJournal_2011-2_Plummer.pdf by Martyn Plummer.\n\n\n1.6.5 Common symbols\nMost OSes (including all those commonly used for R) have the concept of ‘tentative definitions’ where global C variables are defined without an initializer. Traditionally the linker resolves all tentative definitions of the same variable in different object files to the same object, or to a non-tentative definition. However, gcc 10108 and LLVM clang 11109 changed their default so that tentative definitions cannot be merged and the linker will give an error if the same variable is defined in more than one object file. To avoid this, all but one of the C source files should declare the variable extern — which means that any such variables included in header files need to be declared extern. A commonly used idiom (including by R itself) is to define all global variables as extern in a header, say globals.h (and nowhere else), and then in one (and one only) source file use108 see https://gcc.gnu.org/gcc-10/porting_to.html.109 See https://prereleases.llvm.org/11.0.0/rc2/tools/clang/docs/ReleaseNotes.html#modified-compiler-flags.\n#define extern\n# include \"globals.h\"\n#undef extern\nA cleaner approach is not to have global variables at all, but to place in a single file common variables (declared static) followed by all the functions which make use of them: this may result in more efficient code.\nThe ‘modern’ behaviour can be seen110 by using compiler flag -fno-common as part of CFLAGS in earlier versions of gcc and clang.110 In principle this could depend on the OS, but has been checked on Linux and macOS.\n-fno-common is said to be particularly beneficial for ARM cpus.\nThis is not pertinent to C++ which does not permit tentative definitions.\n\n\n1.6.6 C++17 issues\nR 4.3.0 and later default to C++17 when compiling C++, and that finally removed many C++98 features which were deprecated as long ago as C++11. Compiler/runtime authors have been slow to remove these, but LLVM clang with its libc++ runtime library finally started to do so in 2023 – some others warn but some do not.\nThe principal offender is the ‘Boost’ collection of C++ headers and libraries. There are two little-documented ways to work around aspects of its outdated code. One is to add\n-D_HAS_AUTO_PTR_ETC=0\nto PKG_CPPLAGS in src/Makevars, src/Makevars.win and src/Makevars.ucrt. This covers the removal of\nstd::auto_ptr\nstd::unary_function\nstd::binary_function\nstd::random_shuffle\nstd::binder1st\nstd::binder2nd\nwith most issues seen with code that includes boost/functional.hpp, usually indirectly.\nA rarer issue is the use of illegal values for enum types, usually negative ones such as\nBOOST_MPL_AUX_STATIC_CAST(AUX_WRAPPER_VALUE_TYPE, (value - 1));\nin boost/mpl/aux_/integral_wrapper.hpp. Adding\n -Wno-error=enum-constexpr-conversion\nto PKG_CXXFLAGS will allow this, but that flag is only accepted by recent versions of LLVM clang (and will not be in future) so needs a configure test.\nPre=built versions of current clang/libc++ are usually available from https://github.com/llvm/llvm-project/releases for a wide range of platforms (but the Windows builds there are not compatible with Rtools and the macOS ones are unsigned). To select libc++ add -stdlib=libc++ to CXX, for example by having\nCXX=\"/path/to/clang/clang++ -std=gnu++17 -stdlib=libc++\"\nin ~/.R/Makevars.\nAnother build for Windows which may be sufficiently compatible with Rtools can be found at https://github.com/mstorsjo/llvm-mingw: this uses libc++.\n\n\n1.6.7 Portable Fortran code\nUntil recently almost all known R platforms used gfortran as their Fortran compiler, but now there are LLVM and ‘classic’ flang and the Intel compilers ifort111 and ifx are free-of-change.111 announced to be discontinued in 2023.\nThere is still a lot of Fortran code in CRAN packages which predates Fortran 77. Modern Fortran compilers are being written to target a minimum standard of Fortran 2018. and it is desirable that Fortran code in packages complies with that standard. For gfortran this can be checked by adding -std=f2018 to FFLAGS. The most commonly seen issues are\n\nThe use of DFLOAT, which was superseded by DBLE in Fortran 77. Also, use of DCMPLX, DCONJG, DIMAG and similar.\nThe use of GNU Fortran extensions. Some are listed at https://gcc.gnu.org/onlinedocs/gfortran/Extensions-implemented-in-GNU-Fortran.html. Others which have caused problems include etime, getpid, isnan112 and sizeof.\nOne that frequently catches package writers is that it allows out-of-order declarations: in standard-conformant Fortran variables must be declared (explicitly or implicitly) before use in other declarations such as dimensions.\n\n112 There is a portable way to do this in Fortran 2003 (ieee_is_nan() in module ieee_arithmetic), but that was not supported in the versions 4.x of GNU Fortran. A pretty robust alternative is to test if(my_var /= my_var).Unfortunately this flags extensions such as DOUBLE COMPLEX and COMPLEX*16. R has tested that DOUBLE COMPLEX works and so is preferred to -COMPLEX*16. (One can also use something like -COMPLEX(KIND=KIND(0.0D0)).)\nGNU Fortran 10 and later give a compilation error for the previously widespread practice of passing a Fortran array element where an array is expected, or a scalar instead of a length-one array. See https://gcc.gnu.org/gcc-10/porting_to.html. As do the Intel Fortran compilers, and they can be stricter.\nThe use of IMPLICIT NONE is highly recommended – Intel compilers with -warn will warn on variables without an explicit type.\nCommon non-portable constructions include\n\nThe use of Fortran types such as REAL(KIND=8) is very far from portable. According to the standards this merely enumerates different supported types, so DOUBLE PRECISION might be REAL(KIND=3) (and is on an actual compiler). Even if for a particular compiler the value indicates the size in bytes, which values are supported is platform-specific — for example gfortran supports values of 4 and 8 on all current platforms and 10 and 16 on a few (but not for example on all arm CPUs).\nThe same applies to INTEGER(KIND=4) and COMPLEX(KIND=16).\nMany uses of integer and real variable in Fortran code in packages will interwork with C (for example .Fortran is written in C), and R has checked that INTEGER and DOUBLE PRECISION correspond to the C types int and double. To make this explicit, from Fortran 2003 one can use the named constants c_int, c_double and c_double_complex from module iso_c_binding.\nThe Intel compilers only recognize the extensions .f (fixed-form) and .f90 (free-form) and not .f95. R CMD INSTALL works around this for packages without a src/Makefile.\nUse of extensions .F and .F90 to indicate source code to be preprocessed: the preprocessor used is compiler-specific and may or may not be cpp.\n\n\n\n1.6.8 Binary distribution\nIf you want to distribute a binary version of a package on Windows or macOS, there are further checks you need to do to check it is portable: it is all too easy to depend on external software on your own machine that other users will not have.\nFor Windows, check what other DLLs your package’s DLL depends on (‘imports’ from in the DLL tools’ parlance). A convenient GUI-based tool to do so is ‘Dependency Walker’ (https://www.dependencywalker.com/) for both 32-bit and 64-bit DLLs – note that this will report as missing links to R’s own DLLs such as R.dll and Rblas.dll. The command-line tool objdump in the appropriate toolchain will also reveal what DLLs are imported from. If you use a toolchain other than one provided by the R developers or use your own makefiles, watch out in particular for dependencies on the toolchain’s runtime DLLs such as libgfortran, libstdc++ and libgcc_s.\nFor macOS, using R CMD otool -L on the package’s shared object(s) in the libs directory will show what they depend on: watch for any dependencies in /usr/local/lib or /usr/local/gfortran/lib, notably libgfortran.?.dylib and libquadmath.0.dylib. (For ways to fix these, see the section ‘Building binary packages’ in the ‘R Installation and Administration’ manual’.)\nMany people (including the CRAN package repository) will not accept source packages containing binary files as the latter are a security risk. If you want to distribute a source package which needs external software on Windows or macOS, options include\n\nTo arrange for installation of the package to download the additional software from a URL, as e.g. package Cairo used to.\nTo negotiate with Tomas Kalibera to include Windows software in Rtools or with Simon Urbanek to include macOS software in his ‘recipes’ system.\n(For CRAN.) To negotiate with Uwe Ligges to host the additional components on WinBuilder, and write a configure.win file to install them.\n\nBe aware that license requirements you may require you to supply the sources for the additional components (and will if your package has a GPL-like license)." }, { "objectID": "Creating-R-packages.html#diagnostic-messages", @@ -375,7 +375,7 @@ "href": "The-R-API.html#memory-allocation", "title": "6  The R API: entry points for C code", "section": "6.1 Memory allocation", - "text": "6.1 Memory allocation\nThere are two types of memory allocation available to the C programmer, one in which R manages the clean-up and the other in which user has full control (and responsibility).\nThese functions are declared in header R_exts/RS.h which is included by R.h.\n\n6.1.1 Transient storage allocation\nHere R will reclaim the memory at the end of the call to .C, .Call or .External. Use\nchar *R_alloc(size_t n, int size)\nwhich allocates n units of size bytes each. A typical usage (from package stats) is\nx = (int *) R_alloc(nrows(merge)+2, sizeof(int));\n(size_t is defined in stddef.h which the header defining R_alloc includes.)\nThere is a similar call, S_alloc (named for compatibility with older versions of S) which zeroes the memory allocated,\nchar *S_alloc(long n, int size)\nand\nchar *S_realloc(char *p, long new, long old, int size)\nwhich (for new > old) changes the allocation size from old to new units, and zeroes the additional units. NB: these calls are best avoided as long is insufficient for large memory allocations on 64-bit Windows (where it is limited to 2^31-1 bytes).\nThis memory is taken from the heap, and released at the end of the .C, .Call or .External call. Users can also manage it, by noting the current position with a call to vmaxget and subsequently clearing memory allocated by a call to vmaxset. An example might be\nvoid *vmax = vmaxget()\n// a loop involving the use of R_alloc at each iteration\nvmaxset(vmax)\nThis is only recommended for experts.\nNote that this memory will be freed on error or user interrupt (if allowed: see Allowing interrupts).\nThe memory returned is only guaranteed to be aligned as required for double pointers: take precautions if casting to a pointer which needs more. There is also\nlong double *R_allocLD(size_t n)\nwhich is guaranteed to have the 16-byte alignment needed for long double pointers on some platforms.\nThese functions should only be used in code called by .C etc, never from front-ends. They are not thread-safe.\n\n\n6.1.2 User-controlled memory\nThe other form of memory allocation is an interface to malloc, the interface providing R error signaling. This memory lasts until freed by the user and is additional to the memory allocated for the R workspace.\nThe interface macros are\ntype* R_Calloc(size_t n, type)\ntype* R_Realloc(any *p, size_t n, type)\nvoid R_Free(any *p)\nproviding analogues of calloc, realloc and free. If there is an error during allocation it is handled by R, so if these return the memory has been successfully allocated or freed. R_Free will set the pointer p to NULL. (Some but not all versions of S did so.)\nUsers should arrange to R_Free this memory when no longer needed, including on error or user interrupt. This can often be done most conveniently from an on.exit action in the calling R function – see pwilcox for an example.\nDo not assume that memory allocated by R_Calloc/R_Realloc comes from the same pool as used by malloc:2 in particular do not use free or strdup with it.2 That was not the case on Windows prior to R 4.2.0.\nMemory obtained by these macros should be aligned in the same way as malloc, that is ‘suitably aligned for any kind of variable’.\nHistorically the macros Calloc, Free and Realloc were used, and these remain available unless STRICT_R_HEADERS was defined prior to the inclusion of the header.\nchar * CallocCharBuf(size_t n)\nvoid * Memcpy(p, q, n)\nvoid * Memzero(p, m)\nCallocCharBuf is shorthand for R_Calloc(n+1, char) to allow for the nul terminator. Memcpy and Memzero take n items from array p and copy them to array p or zero them respectively." + "text": "6.1 Memory allocation\nThere are two types of memory allocation available to the C programmer, one in which R manages the clean-up and the other in which user has full control (and responsibility).\nThese functions are declared in header R_exts/RS.h which is included by R.h.\n\n6.1.1 Transient storage allocation\nHere R will reclaim the memory at the end of the call to .C, .Call or .External. Use\nchar *R_alloc(size_t n, int size)\nwhich allocates n units of size bytes each. A typical usage (from package stats) is\nx = (int *) R_alloc(nrows(merge)+2, sizeof(int));\n(size_t is defined in stddef.h which the header defining R_alloc includes.)\nThere is a similar call, S_alloc (named for compatibility with older versions of S) which zeroes the memory allocated,\nchar *S_alloc(long n, int size)\nand\nchar *S_realloc(char *p, long new, long old, int size)\nwhich (for new > old) changes the allocation size from old to new units, and zeroes the additional units. NB: these calls are best avoided as long is insufficient for large memory allocations on 64-bit Windows (where it is limited to 2^31-1 bytes).\nThis memory is taken from the heap, and released at the end of the .C, .Call or .External call. Users can also manage it, by noting the current position with a call to vmaxget and subsequently clearing memory allocated by a call to vmaxset. An example might be\nvoid *vmax = vmaxget()\n// a loop involving the use of R_alloc at each iteration\nvmaxset(vmax)\nThis is only recommended for experts.\nNote that this memory will be freed on error or user interrupt (if allowed: see Allowing interrupts).\nThe memory returned is only guaranteed to be aligned as required for double pointers: take precautions if casting to a pointer which needs more. There is also\nlong double *R_allocLD(size_t n)\nwhich is guaranteed to have the 16-byte alignment needed for long double pointers on some platforms.\nThese functions should only be used in code called by .C etc, never from front-ends. They are not thread-safe.\n\n\n6.1.2 User-controlled memory\nThe other form of memory allocation is an interface to malloc, the interface providing R error signaling. This memory lasts until freed by the user and is additional to the memory allocated for the R workspace.\nThe interface macros are\ntype* R_Calloc(size_t n, type)\ntype* R_Realloc(any *p, size_t n, type)\nvoid R_Free(any *p)\nproviding analogues of calloc, realloc and free. If there is an error during allocation it is handled by R, so if these return the memory has been successfully allocated or freed. R_Free will set the pointer p to NULL. (Some but not all versions of S did so.)\nUsers should arrange to R_Free this memory when no longer needed, including on error or user interrupt. This can often be done most conveniently from an on.exit action in the calling R function – see pwilcox for an example.\nDo not assume that memory allocated by R_Calloc/R_Realloc comes from the same pool as used by malloc:2 in particular do not use free or strdup with it.2 That was not the case on Windows prior to R 4.2.0.\nMemory obtained by these macros should be aligned in the same way as malloc, that is ‘suitably aligned for any kind of variable’.\nHistorically the macros Calloc, Free and Realloc were used, and these remain available unless STRICT_R_HEADERS was defined prior to the inclusion of the header.\nchar * CallocCharBuf(size_t n)\nvoid * Memcpy(q, p, n)\nvoid * Memzero(p, n)\nCallocCharBuf(n) is shorthand for R_Calloc(n+1, char) to allow for the nul terminator. Memcpy and Memzero take n items from array p and copy them to array q or zero them respectively." }, { "objectID": "The-R-API.html#error-signaling", diff --git a/r-ints/Function-and-variable-index.html b/r-ints/Function-and-variable-index.html index 6241acd..5451287 100644 --- a/r-ints/Function-and-variable-index.html +++ b/r-ints/Function-and-variable-index.html @@ -691,124 +691,136 @@

Function and variable index

-_R_CHECK_NATIVE_ROUTINE_REGISTRATION_: +_R_CHECK_MBCS_CONVERSION_FAILURE_:   Tools -_R_CHECK_NEWS_IN_PLAIN_TEXT_: +_R_CHECK_NATIVE_ROUTINE_REGISTRATION_:   Tools -_R_CHECK_NO_RECOMMENDED_: +_R_CHECK_NEWS_IN_PLAIN_TEXT_:   Tools -_R_CHECK_NO_STOP_ON_TEST_ERROR_: +_R_CHECK_NO_RECOMMENDED_:   Tools -_R_CHECK_ONE_TEST_ELAPSED_TIMEOUT_: +_R_CHECK_NO_STOP_ON_TEST_ERROR_:   Tools -_R_CHECK_ONE_VIGNETTE_ELAPSED_TIMEOUT_: +_R_CHECK_ONE_TEST_ELAPSED_TIMEOUT_:   Tools -_R_CHECK_ORPHANED_: +_R_CHECK_ONE_VIGNETTE_ELAPSED_TIMEOUT_:   Tools -_R_CHECK_OVERWRITE_REGISTERED_S3_METHODS_: +_R_CHECK_ORPHANED_:   Tools -_R_CHECK_PACKAGES_USED_IN_TESTS_USE_SUBDIRS_: +_R_CHECK_OVERWRITE_REGISTERED_S3_METHODS_:   Tools -_R_CHECK_PERMISSIONS_: +_R_CHECK_PACKAGES_USED_IN_TESTS_USE_SUBDIRS_:   Tools -_R_CHECK_PKGMAN_ELAPSED_TIMEOUT_: +_R_CHECK_PERMISSIONS_:   Tools -_R_CHECK_PKG_SIZES_: +_R_CHECK_PKGMAN_ELAPSED_TIMEOUT_:   Tools -_R_CHECK_PKG_SIZES_THRESHOLD_: +_R_CHECK_PKG_SIZES_:   Tools -_R_CHECK_PRAGMAS_: +_R_CHECK_PKG_SIZES_THRESHOLD_:   Tools -_R_CHECK_RD_ALLOW_EMPTY_ITEM_IN_DESCRIBE_: +_R_CHECK_PRAGMAS_:   Tools -_R_CHECK_RD_CHECKRD_MINLEVEL_: +_R_CHECK_RD_ALLOW_EMPTY_ITEM_IN_DESCRIBE_:   Tools -_R_CHECK_RD_CONTENTS_: +_R_CHECK_RD_CHECKRD_MINLEVEL_:   Tools -_R_CHECK_RD_EXAMPLES_T_AND_F_: +_R_CHECK_RD_CONTENTS_:   Tools -_R_CHECK_RD_LINE_WIDTHS_: +_R_CHECK_RD_EXAMPLES_T_AND_F_:   Tools +_R_CHECK_RD_LINE_WIDTHS_: +  +Tools + + + _R_CHECK_RD_MATH_RENDERING_:   Tools + + +_R_CHECK_RD_NOTE_LOST_BRACES_: +  +Tools + _R_CHECK_RD_STYLE_: diff --git a/r-ints/Tools.html b/r-ints/Tools.html index 3434bb2..874e31e 100644 --- a/r-ints/Tools.html +++ b/r-ints/Tools.html @@ -408,11 +408,15 @@

8 
-

Controls the minimum level for reporting warnings from checkRd. Default: -1.

+

Controls the minimum level for reporting warnings from checkRd(). Default: -1.

+
+
_R_CHECK_RD_NOTE_LOST_BRACES_
+
+

If true, some of the “lost braces” that checkRd() finds in LaTeX-like Rd contexts are reported (by raising their warning level to -1). This will often detect missing initial backslashes for Rd macros, unescaped in-text set braces, and description-like \item{label}{desc} entries within \itemize. Default: unset (but true for CRAN submission checks), currently; may be enabled unconditionally in the future.

_R_CHECK_RD_ALLOW_EMPTY_ITEM_IN_DESCRIBE_
-

Control whether empty items inside \\describe are allowed without a warning. This is a temporary stop gap measure meant to support legacy packages, and is likely to be removed in future versions of R. Default: false.

+

Control whether empty items inside \describe are allowed without a warning. This is a temporary stop gap measure meant to support legacy packages, and is likely to be removed in future versions of R. Default: false.

_R_CHECK_XREFS_REPOSITORIES_
@@ -749,6 +753,10 @@

8  ¶ +
+

If set to a non-empty value, makes warnings from pdf() and postscript() about conversion failures from an MBCS (ususally UTF-8) into errors. Default: unset.

+

The following variables control checks for undeclared/unconditional use of other packages. They work by setting up a temporary library directory and setting .libPaths() to just that and .Library, so are only effective if additional packages are installed somewhere other than .Library. The temporary library is populated by symbolic links1 to installed packages not also in .Library.

  • 1 under Windows, junction points, or copies if environment variable R_WIN_NO_JUNCTIONS has a non-empty value.

    • @@ -815,18 +823,18 @@

    8  _R_CHECK_THINGS_IN_CHECK_DIR_=true _R_CHECK_THINGS_IN_TEMP_DIR_=true _R_CHECK_BASHISMS_=true -_R_CLASS_MATRIX_ARRARY_=true -_R_CHECK_ORPHANED_=true -_R_CHECK_BOGUS_RETURN_=true -_R_CHECK_MATRIX_DATA_=TRUE -_R_CHECK_CODE_CLASS_IS_STRING_=true -_R_CHECK_RD_VALIDATE_RD2HTML_=true -_R_CHECK_RD_MATH_RENDERING_=true -_R_CHECK_NEWS_IN_PLAIN_TEXT_=true -_R_CHECK_BROWSER_NONINTERACTIVE_=true -_R_CHECK_URLS_SHOW_301_STATUS_=true -_R_CHECK_UNDOC_USE_ALL_NAMES_=true -_R_CHECK_S3_METHODS_SHOW_POSSIBLE_ISSUES_=true +_R_CHECK_ORPHANED_=true +_R_CHECK_BOGUS_RETURN_=true +_R_CHECK_MATRIX_DATA_=TRUE +_R_CHECK_CODE_CLASS_IS_STRING_=true +_R_CHECK_RD_VALIDATE_RD2HTML_=true +_R_CHECK_RD_MATH_RENDERING_=true +_R_CHECK_NEWS_IN_PLAIN_TEXT_=true +_R_CHECK_BROWSER_NONINTERACTIVE_=true +_R_CHECK_URLS_SHOW_301_STATUS_=true +_R_CHECK_UNDOC_USE_ALL_NAMES_=true +_R_CHECK_S3_METHODS_SHOW_POSSIBLE_ISSUES_=true +_R_CHECK_RD_NOTE_LOST_BRACES_=true

    These are turned on by R CMD check --as-cran: the incoming checks also use

    _R_CHECK_FORCE_SUGGESTS_=FALSE

    since some packages do suggest other packages not available on CRAN or other commonly-used repositories.

    diff --git a/r-ints/search.json b/r-ints/search.json index 5fff72a..20f01dd 100644 --- a/r-ints/search.json +++ b/r-ints/search.json @@ -249,7 +249,7 @@ "href": "Tools.html", "title": "8  Tools", "section": "", - "text": "The behavior of R CMD check can be controlled through a variety of command line arguments and environment variables.\nThere is an internal --install=value command line argument not shown by R CMD check --help, with possible values\n\ncheck:file\n\nAssume that installation was already performed with stdout/stderr to file, the contents of which need to be checked (without repeating the installation). This is useful for checks applied by repository maintainers: it reduces the check time by the installation time given that the package has already been installed. In this case, one also needs to specify where the package was installed to using command line option --library.\n\nfake\n\nFake installation, and turn off the run-time tests.\n\nskip\n\nSkip installation, e.g., when testing recommended packages bundled with R.\n\nno\n\nThe same as --no-install : turns off installation and the tests which require the package to be installed.\n\n\nThe following environment variables can be used to customize the operation of check: a convenient place to set these is the check environment file (default, ~/.R/check.Renviron).\n\n_R_CHECK_ALL_NON_ISO_C_ ¶\n\nIf true, do not ignore compiler (typically GCC) warnings about non ISO C code in system headers. Note that this may also show additional ISO C++ warnings. Default: false.\n\n_R_CHECK_FORCE_SUGGESTS_ ¶\n\nIf true, give an error if suggested packages are not available. Default: true (but false for CRAN submission checks).\n\n_R_CHECK_RD_CONTENTS_ ¶\n\nIf true, check Rd files for auto-generated content which needs editing, and missing argument documentation. Default: true.\n\n_R_CHECK_RD_LINE_WIDTHS_ ¶\n\nIf true, check Rd line widths in usage and examples sections. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_RD_STYLE_ ¶\n\nIf true, check whether Rd usage entries for S3 methods use the full function name rather than the appropriate \\method markup. Default: true.\n\n_R_CHECK_RD_XREFS_ ¶\n\nIf true, check the cross-references in .Rd files. Default: true.\n\n_R_CHECK_SUBDIRS_NOCASE_ ¶\n\nIf true, check the case of directories such as R and man. Default: true.\n\n_R_CHECK_SUBDIRS_STRICT_ ¶\n\nInitial setting for --check-subdirs. Default: default (which checks only tarballs, and checks in the src only if there is no configure file).\n\n_R_CHECK_USE_CODETOOLS_ ¶\n\nIf true, make use of the codetools package, which provides a detailed analysis of visibility of objects (but may give false positives). Default: true (if recommended packages are installed).\n\n_R_CHECK_USE_INSTALL_LOG_ ¶\n\nIf true, record the output from installing a package as part of its check to a log file (00install.out by default), even when running interactively. Default: true.\n\n_R_CHECK_VIGNETTES_NLINES_ ¶\n\nMaximum number of lines to show from the bottom of the output when reporting errors in running or re-building vignettes. ( Value 0 means all lines will be shown.) Default: 10 for running, 25 for re-building.\n\n_R_CHECK_CODOC_S4_METHODS_ ¶\n\nControl whether codoc() testing is also performed on S4 methods. Default: true.\n\n_R_CHECK_DOT_INTERNAL_ ¶\n\nControl whether the package code is scanned for .Internal calls, which should only be used by base (and occasionally by recommended) packages. Default: true.\n\n_R_CHECK_EXECUTABLES_ ¶\n\nControl checking for executable (binary) files. Default: true.\n\n_R_CHECK_EXECUTABLES_EXCLUSIONS_ ¶\n\nControl whether checking for executable (binary) files ignores files listed in the package’s BinaryFiles file. Default: true (but false for CRAN submission checks). However, most likely this package-level override mechanism will be removed eventually.\n\n_R_CHECK_PERMISSIONS_ ¶\n\nControl whether permissions of files should be checked. Default: true iff .Platform$OS.type == \"unix\".\n\n_R_CHECK_FF_CALLS_ ¶\n\nAllows turning off checkFF() testing. If set to registration, checks the registration information (number of arguments, correct choice of .C/.Fortran/.Call/.External) for such calls provided the package is installed. Default: true.\n\n_R_CHECK_FF_DUP_ ¶\n\nControls checkFF(check_DUP) Default: true (and forced to be true for CRAN submission checks).\n\n_R_CHECK_LICENSE_ ¶\n\nControl whether/how license checks are performed. A possible value is maybe (warn in case of problems, but not about standardizable non-standard license specs). Default: true.\n\n_R_CHECK_RD_EXAMPLES_T_AND_F_ ¶\n\nControl whether check_T_and_F() also looks for “bad” (global) T/F uses in examples. Off by default because this can result in false positives.\n\n_R_CHECK_RD_CHECKRD_MINLEVEL_ ¶\n\nControls the minimum level for reporting warnings from checkRd. Default: -1.\n\n_R_CHECK_RD_ALLOW_EMPTY_ITEM_IN_DESCRIBE_ ¶\n\nControl whether empty items inside \\\\describe are allowed without a warning. This is a temporary stop gap measure meant to support legacy packages, and is likely to be removed in future versions of R. Default: false.\n\n_R_CHECK_XREFS_REPOSITORIES_ ¶\n\nIf set to a non-empty value, a space-separated list of repositories to use to determine known packages. Default: empty, when the CRAN and Bioconductor repositories known to R is used.\n\n_R_CHECK_SRC_MINUS_W_IMPLICIT_ ¶\n\nControl whether installation output is checked for compilation warnings about implicit function declarations (as spotted by GCC with command line option -Wimplicit-function-declaration, which is implied by -Wall). NB: implicit function declarations are errors in some recent C compilers, including Apple clang. Default: true from R 4.2.0, previously false.\n\n_R_CHECK_SRC_MINUS_W_UNUSED_ ¶\n\nControl whether installation output is checked for compilation warnings about unused code constituents (as spotted by GCC with command line option -Wunused, which is implied by -Wall). Default: true.\n\n_R_CHECK_WALL_FORTRAN_ ¶\n\nControl whether gfortran 4.0 or later -Wall warnings are used in the analysis of installation output. Default: false, even though the warnings are justifiable.\n\n_R_CHECK_ASCII_CODE_ ¶\n\nIf true, check R code for non-ascii characters. Default: true.\n\n_R_CHECK_ASCII_DATA_ ¶\n\nIf true, check data for non-ascii characters. En route, checks that all the datasets can be loaded and that their components can be accessed. Default: true.\n\n_R_CHECK_COMPACT_DATA_ ¶\n\nIf true, check data for ascii and uncompressed saves, and also check if using bzip2 or xz compression would be significantly better. Default: true.\n\n_R_CHECK_SKIP_ARCH_ ¶\n\nComma-separated list of architectures that will be omitted from checking in a multi-arch setup. Default: none.\n\n_R_CHECK_SKIP_TESTS_ARCH_ ¶\n\nComma-separated list of architectures that will be omitted from running tests in a multi-arch setup. Default: none.\n\n_R_CHECK_SKIP_EXAMPLES_ARCH_ ¶\n\nComma-separated list of architectures that will be omitted from running examples in a multi-arch setup. Default: none.\n\n_R_CHECK_VC_DIRS_ ¶\n\nShould the unpacked package directory be checked for version-control directories (CVS, .svn …)? Default: true for tarballs.\n\n_R_CHECK_PKG_SIZES_ ¶\n\nShould du be used to find the installed sizes of packages? R CMD check does check for the availability of du. but this option allows the check to be overruled if an unsuitable command is found (including one that does not respect the -k flag to report in units of 1Kb, or reports in a different format – the GNU, macOS and Solaris du commands have been tested). Default: true if du is found.\n\n_R_CHECK_PKG_SIZES_THRESHOLD_ ¶\n\nThreshold used for _R_CHECK_PKG_SIZES_ (in Mb). Default: 5\n\n_R_CHECK_DOC_SIZES_ ¶\n\nShould qpdf be used to check the installed sizes of PDFs? Default: true if qpdf is found.\n\n_R_CHECK_DOC_SIZES2_ ¶\n\nShould gs be used to check the installed sizes of PDFs? This is slower than (and in addition to) the previous check, but does detect figures with excessive detail (often hidden by over-plotting) or bitmap figures with too high a resolution. Requires that R_GSCMD is set to a valid program, or gs (or on Windows, gswin32.exe or gswin64c.exe) is on the path. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_ALWAYS_LOG_VIGNETTE_OUTPUT_ ¶\n\nBy default the output from running the R code in the vignettes is kept only if there is an error. This also applies to the build_vignettes.log log from the re-building of vignettes. Default: false.\n\n_R_CHECK_CLEAN_VIGN_TEST_ ¶\n\nShould the vign_test directory be removed if the test is successful? Default: true.\n\n_R_CHECK_REPLACING_IMPORTS_ ¶\n\nShould warnings about replacing imports be reported? These sometimes come from auto-generated NAMESPACE files in other packages, but most often from importing the whole of a namespace rather than using importFrom. Default: true.\n\n_R_CHECK_UNSAFE_CALLS_ ¶\n\nCheck for calls that appear to tamper with (or allow tampering with) already loaded code not from the current package: such calls may well contravene CRAN policies. Default: true.\n\n_R_CHECK_TIMINGS_ ¶\n\nOptionally report timings for installation, examples, tests and running/re-building vignettes as part of the check log. The format is [as/bs] for the total CPU time (including child processes) a and elapsed time b, except on Windows, when it is [bs]. In most cases timings are only given for OK checks. Times with an elapsed component over 10 mins are reported in minutes (with abbreviation m). The value is the smallest numerical value in elapsed seconds that should be reported: non-numerical values indicate that no report is required, a value of 0 that a report is always required. Default: \"\". (10 for CRAN checks unless set in the environment.)\n\n_R_CHECK_EXAMPLE_TIMING_THRESHOLD_ ¶\n\nIf timings are being recorded, set the threshold in seconds for reporting long-running examples (either user+system CPU time or elapsed time). Default: \"5\".\n\n_R_CHECK_EXAMPLE_TIMING_CPU_TO_ELAPSED_THRESHOLD_ ¶\n\nFor checks with timings enabled, report examples where the ratio of CPU time to elapsed time exceeds this threshold (and the CPU time is at least one second). This can help detect the simultaneous use of multiple CPU cores. Default: NA.\n\n_R_CHECK_TEST_TIMING_CPU_TO_ELAPSED_THRESHOLD_ ¶\n\nReport for running an individual test if the ratio of CPU time to elapsed time exceeds this threshold (and the CPU time is at least one second). Not supported on Windows. Default: NA.\n\n_R_CHECK_VIGNETTE_TIMING_CPU_TO_ELAPSED_THRESHOLD_ ¶\n\nReport if when running/re-building vignettes (individually or in aggregate) the ratio of CPU time to elapsed time exceeds this threshold (and the CPU time is at least one second). Not supported on Windows. Default: NA.\n\n_R_CHECK_INSTALL_TIMING_CPU_TO_ELAPSED_THRESHOLD_ ¶\n\nReport if for installation the ratio of CPU time to elapsed time exceeds this threshold (and the CPU time is at least one second). Not supported on Windows, only uses if _R_CHECK_TIMINGS_ is set Default: NA.\n\n_R_CHECK_CODETOOLS_PROFILE_ ¶\n\nA string with comma-separated name=value pairs (with value a logical constant) giving additional arguments for the codetools functions used for analyzing package code. E.g., use _R_CHECK_CODETOOLS_PROFILE_=\"suppressLocalUnused=FALSE\" to turn off suppressing warnings about unused local variables. Default: no additional arguments, corresponding to using skipWith = TRUE, suppressPartialMatchArgs = FALSE and suppressLocalUnused = TRUE.\n\n_R_CHECK_CRAN_INCOMING_ ¶\n\nCheck whether package is suitable for publication on CRAN. Default: false, except for CRAN submission checks.\n\n_R_CHECK_CRAN_INCOMING_REMOTE_ ¶\n\nInclude checks that require remote access among the above. Default: same as _R_CHECK_CRAN_INCOMING_\n\n_R_CHECK_XREFS_USE_ALIASES_FROM_CRAN_ ¶\n\nWhen checking anchored Rd xrefs, use Rd aliases from the CRAN package web areas in addition to those in the packages installed locally. Default: false.\n\n_R_SHLIB_BUILD_OBJECTS_SYMBOL_TABLES_ ¶\n\nMake the checks of compiled code more accurate by recording the symbol tables for objects (.o files) at installation in a file symbols.rds. (Only currently supported on Linux, Solaris, macOS, Windows and FreeBSD.) Default: true.\n\n_R_CHECK_CODE_ASSIGN_TO_GLOBALENV_ ¶\n\nShould the package code be checked for assignments to the global environment? Default: false (but true for CRAN submission checks).\n\n_R_CHECK_CODE_ATTACH_ ¶\n\nShould the package code be checked for calls to attach()? Default: false (but true for CRAN submission checks).\n\n_R_CHECK_CODE_DATA_INTO_GLOBALENV_ ¶\n\nShould the package code be checked for calls to data() which load into the global environment? Default: false (but true for CRAN submission checks).\n\n_R_CHECK_DOT_FIRSTLIB_ ¶\n\nShould the package code be checked for the presence of the obsolete function .First.lib()? Default: false (but true for CRAN submission checks).\n\n_R_CHECK_DEPRECATED_DEFUNCT_ ¶\n\nShould the package code be checked for the presence of recently deprecated or defunct functions (including completely removed functions). Also for platform-specific graphics devices. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_SCREEN_DEVICE_ ¶\n\nIf set to warn, give a warning if examples etc open a screen device. If set to stop, give an error. Default: empty (but stop for CRAN submission checks).\n\n_R_CHECK_WINDOWS_DEVICE_ ¶\n\nIf set to stop, give an error if a Windows-only device is used in example etc. This is only useful on Windows: the devices do not exist elsewhere. Default: empty (but stop for CRAN submission checks on Windows).\n\n_R_CHECK_TOPLEVEL_FILES_ ¶\n\nReport on top-level files in the package sources that are not described in ‘Writing R Extensions’ nor are commonly understood (like ChangeLog). Variations on standard names (e.g. COPYRIGHT) are also reported. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_GCT_N_ ¶\n\nShould the --use-gct use gctorture2(n) rather than gctorture(TRUE)? Use a positive integer to enable this. Default: 0.\n\n_R_CHECK_LIMIT_CORES_ ¶\n\nIf set, check the usage of too many cores in package parallel. If set to warn gives a warning, to false or FALSE the check is skipped, and any other non-empty value gives an error when more than 2 children are spawned. Default: unset (but TRUE for CRAN submission checks).\n\n_R_CHECK_CODE_USAGE_VIA_NAMESPACES_ ¶\n\nIf set, check code usage (via codetools) directly on the package namespace without loading and attaching the package and its suggests and enhances. Default: true (and true for CRAN submission checks).\n\n_R_CHECK_CODE_USAGE_WITH_ONLY_BASE_ATTACHED_ ¶\n\nIf set, check code usage (via codetools) with only the base package attached. Default: true.\n\n_R_CHECK_EXIT_ON_FIRST_ERROR_ ¶\n\nIf set to a true value, the check will exit on the first error. Default: false.\n\n_R_CHECK_OVERWRITE_REGISTERED_S3_METHODS_ ¶\n\nIf set to a true value, report already registered S3 methods in base/recommended packages which are overwritten when this package’s namespace is loaded. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_TESTS_NLINES_ ¶\n\nNumber of trailing lines of test output to reproduce in the log. If 0 all lines except the R preamble are reproduced. Default: 13.\n\n_R_CHECK_NATIVE_ROUTINE_REGISTRATION_ ¶\n\nIf set to a true value, report if the entry points to register native routines and to suppress dynamic search are not found in a package’s DLL. (NB: this requires system command nm to be on the PATH. On Windows, objdump.exe is first searched for in compiler toolchain specified via Makeconf (can be customized by environment variable BINPREF). If not found there, it must be on the PATH. On Unix this would be normal when using a package with compiled code (which are the only ones this checks), but Windows’ users should check. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_NO_STOP_ON_TEST_ERROR_ ¶\n\nIf set to a true value, do not stop running tests after first error (as if command line option --no-stop-on-test-error had been given). Default: false (but true for CRAN submission checks).\n\n_R_CHECK_PRAGMAS_ ¶\n\nRun additional checks on the pragmas in C/C++ source code and headers. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_COMPILATION_FLAGS_ ¶\n\nIf the package is installed and has C/C++/Fortran code, check the install log for non-portable flags (for example those added to src/Makevars during configuration). Currently -W flags are reported, except -Wall, -Wextra and -Weverything, and flags which appear to be attempts to suppress warnings are highlighted. See section ‘Writing portable packages’ in the ‘Writing R Extensions’ manual for the rationale of this check (and why even -Werror is unsafe).\nEnvironment variable _R_CHECK_COMPILATION_FLAGS_KNOWN_ can be set to a space-separated set of flags which come from the R build used for testing (flags such as -Wall and -Wextra are already known). For example, for CRAN builds of R >= 4.0.0 on macOS one could use\n_R_CHECK_COMPILATION_FLAGS_KNOWN_=\"-mmacosx-version-min=10.13\" \nDefault: unset.\n\n_R_CHECK_R_DEPENDS_ ¶\n\nCheck that any dependence on R is not on a recent patch-level version such as R (>= 3.3.3) since blocking installation of a package will also block its reverse dependencies. Possible values \"note\", \"warn\" and logical values (where currently true values are equivalent to \"note\"). Default: false (but \"warn\" for --as-cran).\n\n_R_CHECK_SERIALIZATION_ ¶\n\nCheck that serialized R objects in the package sources were serialized with version 2 and there is no dependence on R >= 3.5.0. (Version 3 is in use as from R 3.5.0 but should only be used when necessary.) Default: false (but true for CRAN submission checks).\n\n_R_CHECK_R_ON_PATH_ ¶\n\nThis checks if the package attempts to use R or Rscript from the path rather than that under test. It does so by putting scripts at the head of the path which print a message and fail. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_PACKAGES_USED_IN_TESTS_USE_SUBDIRS_ ¶\n\nIf set to a true value, also check the R code in common unit test subdirectories of tests for undeclared package dependencies. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_SHLIB_OPENMP_FLAGS_ ¶\n\nCheck correct and portable use of SHLIB_OPENMP_*FLAGS in src/Makevars (and similar). Default: false (but true for CRAN submission checks).\n\n_R_CHECK_CONNECTIONS_LEFT_OPEN_ ¶\n\nWhen checking examples, check for each example if connections are left open: if any are found, this is reported with a fatal error. NB: ‘connections’ includes most use of files and any parallel clusters which have not be stopped by stopCluster(). Default: false (but true for CRAN submission checks).\n\n_R_CHECK_FUTURE_FILE_TIMESTAMPS_ ¶\n\nCheck if any of the input files has a timestamp in the future (and to do so, checks that the system clock is correct to within 5 minutes). Default: false (but true for CRAN submission checks).\n\n_R_CHECK_LENGTH_1_CONDITION_ ¶\n\nNo longer in use: conditions of length greater than one in if or while statements are now an error.\n\n_R_CHECK_VIGNETTES_SKIP_RUN_MAYBE_ ¶\n\nShould running the R code in the vignettes be skipped if vignette outputs are to be rebuilt (which will involve running that code). Default: false (but true for CRAN checking)\n\n_R_CHECK_BUILD_VIGNETTES_SEPARATELY_ ¶\n\nPrior to R 3.6.0, re-building the vignette outputs was done in a single R session which allowed accidental reliance of one vignette on another (for example, in the loading of packages). The current default is to use a separate session for each vignette; this option allows testing the older behaviour, Default: true\n\n_R_CHECK_SYSTEM_CLOCK_ ¶\n\nAs part of the ‘checking for future file timestamps’ enabled by --as-cran, check the system clock against an external clock to catch errors such as the wrong day or even year. Not necessary on systems doing repeated checks. Default: true (but false for CRAN checking)\n\n_R_CHECK_AUTOCONF_ ¶\n\nFor packages with a configure file generated by GNU autoconf and either configure.ac or configure,.in, check that autoreconf can, if available, be run in a copy of the sources (this will detect missing source files and report autoconf warnings). Environment variable AUTORECONf controls the command used: it can give the full path to autoreconf (without spaces) and can include flags such as --warnings=obsolete (which is added for autoreconf version 2.68 or 2.69 and is the default for later versions). Default: false (but true for CRAN submission checks).\n\n_R_CHECK_DATALIST_ ¶\n\nCheck whether file data/datalist is out-of-date. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_THINGS_IN_CHECK_DIR_ ¶\n\nCheck and report at the end of the check run if files have been left in the check directory. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_THINGS_IN_TEMP_DIR_ ¶\n\nCheck and report at the end of tthe check run if files would have been left in the temporary directory (usually /tmp on a Unix-alike). It does this by setting the environment variable TEMPDIR to a subdirectory of the R session directory for the check process: if any files or directories are left there they are removed. Since some of these might be out of the user’s control, environment variable _R_CHECK_THINGS_IN_TEMP_DIR_EXCLUDE_ can specify an (extended regex) pattern of file paths not to be reported – CRAN uses ^ompi. for directories left behind by OpenMPI. There are rare instances where TEMPDIR is not respected and so files are left in /tmp (and not reported, but see the next item): one example is /tmp/boost_interprocess on some OSes. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_THINGS_IN_OTHER_DIRS_ ¶\n\nCheck and report at the end of the check run if new files or directories are created in a selected set of directories during the check run. (This is confined to files owned by the user running the check process.) Currently the directories monitored are the home directory, /tmp (excluding RtmpXXXXXX dirs), /dav/shm, ~/.cache (recursively) and ~/.local/share (recursively) or their equivalents on Windows and macOS (the directories in which the default settings for tools::R_user_dir() use a R subdirectory). Additional directories can be specified in environment variable _R_CHECK_THINGS_IN_OTHER_DIRS_XTRA_, separated by semicolons. Directories are reported with a trailing / on all platforms.\nEnvironment variable _R_CHECK_THINGS_IN_OTHER_DIRS_EXCLUDE_ can specify an (extended regex) pattern of file paths not to be reported – this should match absolute file paths with home represented by ~. For example, on a Linux system\n'^~/.cache/(mozilla/firefox|mesa_shader_cache)/'\nmatches cache directories used by Firefox and OpenGL (and their content). If the value starts with @ it is considered as a filepath which is read with each line treated as a pattern to be matched.\nNote that other processes (include check runs in parallel) may create new files in these directories which will get reported. However, this optional check is very useful for narrowing down possible packages which are leaving behind unexpected files. Default: false\n\n_R_CHECK_BASHISMS_ ¶\n\nCheck the top-level scripts configure (unless generated by autoconf) and cleanup for non-Bourne-shell code, using the Perl script checkbashisms if available. This includes reporting scripts using the non-portable #! /bin/bash. (Script checkbashisms is available in most Linux distributions in a package named either devscripts or devscripts-checkbashisms and from https://sourceforge.net/projects/checkbaskisms/files.) Default: false (but true for CRAN submission checks except on Windows).\n\n_R_CHECK_ORPHANED_ ¶\n\nCheck if dependencies are orphaned packages. As from R 4.1.0 this checks strict dependencies recursively, so will report any orphaned packages which are needed to attach the package by library() as well as any orphaned packages which are suggested. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_EXCESSIVE_IMPORTS_ ¶\n\nA positive integer. If set, give a NOTE if the number of imports from non-base packages exceed this threshold. Large numbers of imports make a package vulnerable to any of them becoming unavailable. Default: unset (but 20 for CRAN submission checks)\n\n_R_CHECK_DONTTEST_EXAMPLES_ ¶\n\nIf true and examples are found with \\donttest sections, the tests are run in one pass with these commented out and then in a second pass including the \\donttest sections, (for the main architecture only). Only for the first pass are the results compared to any .Rout.save file and timings analysed. Overridden by --run-donttest. Default: false unless --as-cran is specified (which can be overridden by setting _R_CHECK_DONTTEST_EXAMPLES_=false).\n\n_R_CHECK_XREFS_PKGS_ARE_DECLARED_ ¶\n\nCheck if packages used in ‘anchored’ cross-references in .Rd files (those of the form \\link[pkg]{foo} and \\link[pkg:bar]{foo}) are declared in the DESCRIPTION file and so these links can be checked. Default: false.\n\n_R_CHECK_XREFS_MIND_SUSPECT_ANCHORS_ ¶\n\nCheck if package-anchored Rd cross-references are to files (and not aliases). Default: false.\n\n_R_CHECK_BOGUS_RETURN_ ¶\n\nIf true and _R_CHECK_USE_CODETOOLS_ is also true, functions are scanned for use of return rather than return(). Default: false (but true for CRAN submission checks).\n\n_R_CHECK_MATRIX_DATA_ ¶\n\nBy default, the check for a mismatch between the data length and the dimensions in a call to matrix gives a warning: setting this to a true value gives an error with a compact traceback. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_CODE_CLASS_IS_STRING_ ¶\n\nCheck if package code has if() condition which compare the class of an object to a string. See https://blog.r-project.org/2019/11/09/when-you-think-class.-think-again/ why this is a bad idea. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_RD_VALIDATE_RD2HTML_ ¶\n\nCheck the validity of the package HTML help pages using HTML Tidy (https://www.html-tidy.org/) (if a suitable version is available on the system path for executables or its path is specified by environment variable R_TIDYCMD). macOS users are advised to install 5.8.0 or later from https://binaries.html-tidy.org/. Default: false (but true for CRAN submission checks). --as-cran can be overridden by setting this variable to a false value.\n\n_R_CHECK_RD_MATH_RENDERING_ ¶\n\nCheck whether HTML math rendering via KaTeX works (if package V8 is available). See https://blog.r-project.org/2022/04/08/enhancements-to-html-documentation/. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_NEWS_IN_PLAIN_TEXT_ ¶\n\nCheck whether news() can successfully read package news in plain text (file NEWS) format. Default: false (but true for CRAN submission checks).\n\n_R_WIN_CHECK_INVALID_PARAMETERS_ ¶\n\nCheck whether arguments passed to the Windows C runtime are valid. When enabled and a C runtime function is called with an invalid parameter, R prints diagnostic information and unconditionally terminates. By default, R for Windows following MinGW-W64 default causes UCRT to ignore invalid parameters, but they may cause R to abort e.g. when R is embedded into applications built with a different compiler toolchain. One may set the value to \"watson\" for interactive debugging on Windows via _invoke_watson. Default: disabled.\n\n_R_CHECK_BROWSER_NONINTERACTIVE_ ¶\n\nIf set to a true value, trap non-interactive debugger invocations. These are most likely caused by leftover browser() statements in package code. Default: unset (but true for CRAN submission checks).\n\n_R_CHECK_URLS_SHOW_301_STATUS_ ¶\n\nIf set to a true value, checking URLs show check status 301 for HTTP response status code “301 Moved Permanently”. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_UNDOC_USE_ALL_NAMES_ ¶\n\nIf set to a true value, checking for undocumented objects does not ignore objects with names starting with a dot (which prior to the advent of namespaces conventionally were considered as “internal”). Default: false (but true for CRAN submission checks).\n\n_R_CHECK_S3_METHODS_SHOW_POSSIBLE_ISSUES_ ¶\n\nDefault: false (but true for CRAN submission checks). If set to a true value, checking S3 methods also notes “possible issues”, including issues with apparent methods not registered and methods registered for non-generics. Default: false (but true for CRAN submission checks).\n\n\nThe following variables control checks for undeclared/unconditional use of other packages. They work by setting up a temporary library directory and setting .libPaths() to just that and .Library, so are only effective if additional packages are installed somewhere other than .Library. The temporary library is populated by symbolic links1 to installed packages not also in .Library.1 under Windows, junction points, or copies if environment variable R_WIN_NO_JUNCTIONS has a non-empty value.\n\n_R_CHECK_INSTALL_DEPENDS_ ¶\n\nIf set to a true value and a test installation is to be done, this is done with a temporary library populated by all the Depends/Imports/LinkingTo packages. Default: false (but true for CRAN submission checks).\nNote that this is actually implemented in R CMD INSTALL, so it is available to those who first install recording to a log, then call R CMD check.\n\n_R_CHECK_SUGGESTS_ONLY_ ¶\n\nIf set to a true value, running examples, tests and vignettes is done with a temporary library directory populated by all the Depends/Imports/Suggests packages. (As exceptions, packages in a VignetteBuilder field are always made available.) Default: false (but true for CRAN submission checks: some of the regular checks use true and some use false).\n\n_R_CHECK_DEPENDS_ONLY_ ¶\n\nAs for _R_CHECK_SUGGESTS_ONLY_ but using only Depends/Imports (and the exceptions, including test-suite managers in Suggests). Default: false\n\n_R_CHECK_DEPENDS_ONLY_DATA_ ¶\n\nApply _R_CHECK_DEPENDS_ONLY_ only to the check of loading from the data directory, so checks if any dataset depends on packages which are in Suggests or undeclared. Default: false (but true for CRAN submission checks)\n\n\n_R_CHECK_DEPENDS_ONLY_EXAMPLES_ ¶\n_R_CHECK_DEPENDS_ONLY_TESTS_ ¶\n_R_CHECK_DEPENDS_ONLY_VIGNETTES_ ¶\n: Apply _R_CHECK_DEPENDS_ONLY_ only to the checking of examples, tests or vignettes. These can be used on their own, or with a false value to override _R_CHECK_DEPENDS_ONLY_. Default: the value of _R_CHECK_DEPENDS_ONLY_ or false if that is unset.\n\n_R_CHECK_NO_RECOMMENDED_ ¶\n\nIf set to a true value, augment the previous checks to make recommended packages unavailable unless declared (even if installed in .Library). Default: false (but true for CRAN submission checks).\nThis may give false positives on code which uses grDevices::densCols and stats:::.asSparse / stats:::.Diag as these invoke KernSmooth and Matrix respectively. (Those in stats are called from various contrasts functions if sparse = TRUE is used.)\n\n\nCRAN’s submission checks use something like\n_R_CHECK_CRAN_INCOMING_=TRUE\n_R_CHECK_CRAN_INCOMING_REMOTE_=TRUE\n_R_CHECK_VC_DIRS_=TRUE\n_R_CHECK_TIMINGS_=10\n_R_CHECK_INSTALL_DEPENDS_=TRUE\n_R_CHECK_SUGGESTS_ONLY_=TRUE\n_R_CHECK_NO_RECOMMENDED_=TRUE\n_R_CHECK_EXECUTABLES_EXCLUSIONS_=FALSE\n_R_CHECK_DOC_SIZES2_=TRUE\n_R_CHECK_CODE_ASSIGN_TO_GLOBALENV_=TRUE\n_R_CHECK_CODE_ATTACH_=TRUE\n_R_CHECK_CODE_DATA_INTO_GLOBALENV_=TRUE\n_R_CHECK_CODE_USAGE_VIA_NAMESPACES_=TRUE\n_R_CHECK_DOT_FIRSTLIB_=TRUE\n_R_CHECK_DEPRECATED_DEFUNCT_=TRUE\n_R_CHECK_REPLACING_IMPORTS_=TRUE\n_R_CHECK_SCREEN_DEVICE_=stop\n_R_CHECK_TOPLEVEL_FILES_=TRUE\n_R_CHECK_OVERWRITE_REGISTERED_S3_METHODS_=TRUE\n_R_CHECK_PRAGMAS_=TRUE\n_R_CHECK_COMPILATION_FLAGS_=TRUE\n_R_CHECK_R_DEPENDS_=warn\n_R_CHECK_SERIALIZATION_=TRUE\n_R_CHECK_R_ON_PATH_=TRUE\n_R_CHECK_PACKAGES_USED_IN_TESTS_USE_SUBDIRS_=TRUE\n_R_CHECK_SHLIB_OPENMP_FLAGS_=TRUE\n_R_CHECK_CONNECTIONS_LEFT_OPEN_=TRUE\n_R_CHECK_FUTURE_FILE_TIMESTAMPS_=TRUE\n_R_CHECK_AUTOCONF_=true\n_R_CHECK_DATALIST_=true\n_R_CHECK_THINGS_IN_CHECK_DIR_=true\n_R_CHECK_THINGS_IN_TEMP_DIR_=true\n_R_CHECK_BASHISMS_=true\n_R_CLASS_MATRIX_ARRARY_=true\n_R_CHECK_ORPHANED_=true\n_R_CHECK_BOGUS_RETURN_=true\n_R_CHECK_MATRIX_DATA_=TRUE\n_R_CHECK_CODE_CLASS_IS_STRING_=true\n_R_CHECK_RD_VALIDATE_RD2HTML_=true\n_R_CHECK_RD_MATH_RENDERING_=true\n_R_CHECK_NEWS_IN_PLAIN_TEXT_=true\n_R_CHECK_BROWSER_NONINTERACTIVE_=true\n_R_CHECK_URLS_SHOW_301_STATUS_=true\n_R_CHECK_UNDOC_USE_ALL_NAMES_=true\n_R_CHECK_S3_METHODS_SHOW_POSSIBLE_ISSUES_=true\nThese are turned on by R CMD check --as-cran: the incoming checks also use\n_R_CHECK_FORCE_SUGGESTS_=FALSE\nsince some packages do suggest other packages not available on CRAN or other commonly-used repositories.\nSeveral environment variables can be used to set ‘timeouts’: limits for the elapsed time taken by the sub-processes used for parts of the checks. A value of 0 indicates no limit, and is the default. Character strings ending in s, m or h indicate a number of seconds, minutes or hours respectively: other values are interpreted as a whole number of seconds (with invalid inputs being treated as no limit).\n\n_R_CHECK_ELAPSED_TIMEOUT_ ¶\n\nThe default timeout for sub-processes not otherwise mentioned, and the default value for all except _R_CHECK_ONE_TEST_ELAPSED_TIMEOUT_. (This is also used by tools::check_packages_in_dir.)\n\n_R_CHECK_INSTALL_ELAPSED_TIMEOUT_ ¶\n\nLimit for when R CMD INSTALL is run by check.\n\n_R_CHECK_EXAMPLES_ELAPSED_TIMEOUT_ ¶\n\nLimit for running all the examples for one sub-architecture.\n\n_R_CHECK_ONE_TEST_ELAPSED_TIMEOUT_ ¶\n\nLimit for running one test for one sub-architecture. Default _R_CHECK_TESTS_ELAPSED_TIMEOUT_.\n\n_R_CHECK_TESTS_ELAPSED_TIMEOUT_ ¶\n\nLimit for running all the tests for one sub-architecture (and the default limit for running one test).\n\n_R_CHECK_ONE_VIGNETTE_ELAPSED_TIMEOUT_ ¶\n\nLimit for running the R code in one vignette, including for re-building each vignette separately.\n\n_R_CHECK_BUILD_VIGNETTES_ELAPSED_TIMEOUT_ ¶\n\nLimit for re-building all vignettes.\n\n_R_CHECK_PKGMAN_ELAPSED_TIMEOUT_ ¶\n\nLimit for each attempt at building the PDF package manual.\n\n\nAnother variable which enables stricter checks is to set R_CHECK_CONSTANTS to 5. This checks that nothing2 changes the values of ‘constants’3 in R code. This is best used in conjunction with setting R_JIT_STRATEGY to 3, which checks code on first use (by default most code is only checked after byte-compilation on second use). Unfortunately these checks slow down checking of examples, tests and vignettes, typically two-fold but in the worst cases at least a hundred-fold.2 The usual culprits are calls to compiled code via .Call or .External which alter their arguments.3 things which the byte compiler assumes do not change, e.g. function bodies.\nThe following environment variables can be used to customize the operation of INSTALL.\n\n_R_INSTALL_LIBS_ONLY_FORCE_DEPENDS_IMPORTS_ ¶\n\nIf true, give an error if installing only package libraries via --libs-only and some package imported or depended on is not available. Default: true (false only for special applications, which analyze native code of packages).\n\n\nFootnotes" + "text": "The behavior of R CMD check can be controlled through a variety of command line arguments and environment variables.\nThere is an internal --install=value command line argument not shown by R CMD check --help, with possible values\n\ncheck:file\n\nAssume that installation was already performed with stdout/stderr to file, the contents of which need to be checked (without repeating the installation). This is useful for checks applied by repository maintainers: it reduces the check time by the installation time given that the package has already been installed. In this case, one also needs to specify where the package was installed to using command line option --library.\n\nfake\n\nFake installation, and turn off the run-time tests.\n\nskip\n\nSkip installation, e.g., when testing recommended packages bundled with R.\n\nno\n\nThe same as --no-install : turns off installation and the tests which require the package to be installed.\n\n\nThe following environment variables can be used to customize the operation of check: a convenient place to set these is the check environment file (default, ~/.R/check.Renviron).\n\n_R_CHECK_ALL_NON_ISO_C_ ¶\n\nIf true, do not ignore compiler (typically GCC) warnings about non ISO C code in system headers. Note that this may also show additional ISO C++ warnings. Default: false.\n\n_R_CHECK_FORCE_SUGGESTS_ ¶\n\nIf true, give an error if suggested packages are not available. Default: true (but false for CRAN submission checks).\n\n_R_CHECK_RD_CONTENTS_ ¶\n\nIf true, check Rd files for auto-generated content which needs editing, and missing argument documentation. Default: true.\n\n_R_CHECK_RD_LINE_WIDTHS_ ¶\n\nIf true, check Rd line widths in usage and examples sections. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_RD_STYLE_ ¶\n\nIf true, check whether Rd usage entries for S3 methods use the full function name rather than the appropriate \\method markup. Default: true.\n\n_R_CHECK_RD_XREFS_ ¶\n\nIf true, check the cross-references in .Rd files. Default: true.\n\n_R_CHECK_SUBDIRS_NOCASE_ ¶\n\nIf true, check the case of directories such as R and man. Default: true.\n\n_R_CHECK_SUBDIRS_STRICT_ ¶\n\nInitial setting for --check-subdirs. Default: default (which checks only tarballs, and checks in the src only if there is no configure file).\n\n_R_CHECK_USE_CODETOOLS_ ¶\n\nIf true, make use of the codetools package, which provides a detailed analysis of visibility of objects (but may give false positives). Default: true (if recommended packages are installed).\n\n_R_CHECK_USE_INSTALL_LOG_ ¶\n\nIf true, record the output from installing a package as part of its check to a log file (00install.out by default), even when running interactively. Default: true.\n\n_R_CHECK_VIGNETTES_NLINES_ ¶\n\nMaximum number of lines to show from the bottom of the output when reporting errors in running or re-building vignettes. ( Value 0 means all lines will be shown.) Default: 10 for running, 25 for re-building.\n\n_R_CHECK_CODOC_S4_METHODS_ ¶\n\nControl whether codoc() testing is also performed on S4 methods. Default: true.\n\n_R_CHECK_DOT_INTERNAL_ ¶\n\nControl whether the package code is scanned for .Internal calls, which should only be used by base (and occasionally by recommended) packages. Default: true.\n\n_R_CHECK_EXECUTABLES_ ¶\n\nControl checking for executable (binary) files. Default: true.\n\n_R_CHECK_EXECUTABLES_EXCLUSIONS_ ¶\n\nControl whether checking for executable (binary) files ignores files listed in the package’s BinaryFiles file. Default: true (but false for CRAN submission checks). However, most likely this package-level override mechanism will be removed eventually.\n\n_R_CHECK_PERMISSIONS_ ¶\n\nControl whether permissions of files should be checked. Default: true iff .Platform$OS.type == \"unix\".\n\n_R_CHECK_FF_CALLS_ ¶\n\nAllows turning off checkFF() testing. If set to registration, checks the registration information (number of arguments, correct choice of .C/.Fortran/.Call/.External) for such calls provided the package is installed. Default: true.\n\n_R_CHECK_FF_DUP_ ¶\n\nControls checkFF(check_DUP) Default: true (and forced to be true for CRAN submission checks).\n\n_R_CHECK_LICENSE_ ¶\n\nControl whether/how license checks are performed. A possible value is maybe (warn in case of problems, but not about standardizable non-standard license specs). Default: true.\n\n_R_CHECK_RD_EXAMPLES_T_AND_F_ ¶\n\nControl whether check_T_and_F() also looks for “bad” (global) T/F uses in examples. Off by default because this can result in false positives.\n\n_R_CHECK_RD_CHECKRD_MINLEVEL_ ¶\n\nControls the minimum level for reporting warnings from checkRd(). Default: -1.\n\n_R_CHECK_RD_NOTE_LOST_BRACES_ ¶\n\nIf true, some of the “lost braces” that checkRd() finds in LaTeX-like Rd contexts are reported (by raising their warning level to -1). This will often detect missing initial backslashes for Rd macros, unescaped in-text set braces, and description-like \\item{label}{desc} entries within \\itemize. Default: unset (but true for CRAN submission checks), currently; may be enabled unconditionally in the future.\n\n_R_CHECK_RD_ALLOW_EMPTY_ITEM_IN_DESCRIBE_ ¶\n\nControl whether empty items inside \\describe are allowed without a warning. This is a temporary stop gap measure meant to support legacy packages, and is likely to be removed in future versions of R. Default: false.\n\n_R_CHECK_XREFS_REPOSITORIES_ ¶\n\nIf set to a non-empty value, a space-separated list of repositories to use to determine known packages. Default: empty, when the CRAN and Bioconductor repositories known to R is used.\n\n_R_CHECK_SRC_MINUS_W_IMPLICIT_ ¶\n\nControl whether installation output is checked for compilation warnings about implicit function declarations (as spotted by GCC with command line option -Wimplicit-function-declaration, which is implied by -Wall). NB: implicit function declarations are errors in some recent C compilers, including Apple clang. Default: true from R 4.2.0, previously false.\n\n_R_CHECK_SRC_MINUS_W_UNUSED_ ¶\n\nControl whether installation output is checked for compilation warnings about unused code constituents (as spotted by GCC with command line option -Wunused, which is implied by -Wall). Default: true.\n\n_R_CHECK_WALL_FORTRAN_ ¶\n\nControl whether gfortran 4.0 or later -Wall warnings are used in the analysis of installation output. Default: false, even though the warnings are justifiable.\n\n_R_CHECK_ASCII_CODE_ ¶\n\nIf true, check R code for non-ascii characters. Default: true.\n\n_R_CHECK_ASCII_DATA_ ¶\n\nIf true, check data for non-ascii characters. En route, checks that all the datasets can be loaded and that their components can be accessed. Default: true.\n\n_R_CHECK_COMPACT_DATA_ ¶\n\nIf true, check data for ascii and uncompressed saves, and also check if using bzip2 or xz compression would be significantly better. Default: true.\n\n_R_CHECK_SKIP_ARCH_ ¶\n\nComma-separated list of architectures that will be omitted from checking in a multi-arch setup. Default: none.\n\n_R_CHECK_SKIP_TESTS_ARCH_ ¶\n\nComma-separated list of architectures that will be omitted from running tests in a multi-arch setup. Default: none.\n\n_R_CHECK_SKIP_EXAMPLES_ARCH_ ¶\n\nComma-separated list of architectures that will be omitted from running examples in a multi-arch setup. Default: none.\n\n_R_CHECK_VC_DIRS_ ¶\n\nShould the unpacked package directory be checked for version-control directories (CVS, .svn …)? Default: true for tarballs.\n\n_R_CHECK_PKG_SIZES_ ¶\n\nShould du be used to find the installed sizes of packages? R CMD check does check for the availability of du. but this option allows the check to be overruled if an unsuitable command is found (including one that does not respect the -k flag to report in units of 1Kb, or reports in a different format – the GNU, macOS and Solaris du commands have been tested). Default: true if du is found.\n\n_R_CHECK_PKG_SIZES_THRESHOLD_ ¶\n\nThreshold used for _R_CHECK_PKG_SIZES_ (in Mb). Default: 5\n\n_R_CHECK_DOC_SIZES_ ¶\n\nShould qpdf be used to check the installed sizes of PDFs? Default: true if qpdf is found.\n\n_R_CHECK_DOC_SIZES2_ ¶\n\nShould gs be used to check the installed sizes of PDFs? This is slower than (and in addition to) the previous check, but does detect figures with excessive detail (often hidden by over-plotting) or bitmap figures with too high a resolution. Requires that R_GSCMD is set to a valid program, or gs (or on Windows, gswin32.exe or gswin64c.exe) is on the path. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_ALWAYS_LOG_VIGNETTE_OUTPUT_ ¶\n\nBy default the output from running the R code in the vignettes is kept only if there is an error. This also applies to the build_vignettes.log log from the re-building of vignettes. Default: false.\n\n_R_CHECK_CLEAN_VIGN_TEST_ ¶\n\nShould the vign_test directory be removed if the test is successful? Default: true.\n\n_R_CHECK_REPLACING_IMPORTS_ ¶\n\nShould warnings about replacing imports be reported? These sometimes come from auto-generated NAMESPACE files in other packages, but most often from importing the whole of a namespace rather than using importFrom. Default: true.\n\n_R_CHECK_UNSAFE_CALLS_ ¶\n\nCheck for calls that appear to tamper with (or allow tampering with) already loaded code not from the current package: such calls may well contravene CRAN policies. Default: true.\n\n_R_CHECK_TIMINGS_ ¶\n\nOptionally report timings for installation, examples, tests and running/re-building vignettes as part of the check log. The format is [as/bs] for the total CPU time (including child processes) a and elapsed time b, except on Windows, when it is [bs]. In most cases timings are only given for OK checks. Times with an elapsed component over 10 mins are reported in minutes (with abbreviation m). The value is the smallest numerical value in elapsed seconds that should be reported: non-numerical values indicate that no report is required, a value of 0 that a report is always required. Default: \"\". (10 for CRAN checks unless set in the environment.)\n\n_R_CHECK_EXAMPLE_TIMING_THRESHOLD_ ¶\n\nIf timings are being recorded, set the threshold in seconds for reporting long-running examples (either user+system CPU time or elapsed time). Default: \"5\".\n\n_R_CHECK_EXAMPLE_TIMING_CPU_TO_ELAPSED_THRESHOLD_ ¶\n\nFor checks with timings enabled, report examples where the ratio of CPU time to elapsed time exceeds this threshold (and the CPU time is at least one second). This can help detect the simultaneous use of multiple CPU cores. Default: NA.\n\n_R_CHECK_TEST_TIMING_CPU_TO_ELAPSED_THRESHOLD_ ¶\n\nReport for running an individual test if the ratio of CPU time to elapsed time exceeds this threshold (and the CPU time is at least one second). Not supported on Windows. Default: NA.\n\n_R_CHECK_VIGNETTE_TIMING_CPU_TO_ELAPSED_THRESHOLD_ ¶\n\nReport if when running/re-building vignettes (individually or in aggregate) the ratio of CPU time to elapsed time exceeds this threshold (and the CPU time is at least one second). Not supported on Windows. Default: NA.\n\n_R_CHECK_INSTALL_TIMING_CPU_TO_ELAPSED_THRESHOLD_ ¶\n\nReport if for installation the ratio of CPU time to elapsed time exceeds this threshold (and the CPU time is at least one second). Not supported on Windows, only uses if _R_CHECK_TIMINGS_ is set Default: NA.\n\n_R_CHECK_CODETOOLS_PROFILE_ ¶\n\nA string with comma-separated name=value pairs (with value a logical constant) giving additional arguments for the codetools functions used for analyzing package code. E.g., use _R_CHECK_CODETOOLS_PROFILE_=\"suppressLocalUnused=FALSE\" to turn off suppressing warnings about unused local variables. Default: no additional arguments, corresponding to using skipWith = TRUE, suppressPartialMatchArgs = FALSE and suppressLocalUnused = TRUE.\n\n_R_CHECK_CRAN_INCOMING_ ¶\n\nCheck whether package is suitable for publication on CRAN. Default: false, except for CRAN submission checks.\n\n_R_CHECK_CRAN_INCOMING_REMOTE_ ¶\n\nInclude checks that require remote access among the above. Default: same as _R_CHECK_CRAN_INCOMING_\n\n_R_CHECK_XREFS_USE_ALIASES_FROM_CRAN_ ¶\n\nWhen checking anchored Rd xrefs, use Rd aliases from the CRAN package web areas in addition to those in the packages installed locally. Default: false.\n\n_R_SHLIB_BUILD_OBJECTS_SYMBOL_TABLES_ ¶\n\nMake the checks of compiled code more accurate by recording the symbol tables for objects (.o files) at installation in a file symbols.rds. (Only currently supported on Linux, Solaris, macOS, Windows and FreeBSD.) Default: true.\n\n_R_CHECK_CODE_ASSIGN_TO_GLOBALENV_ ¶\n\nShould the package code be checked for assignments to the global environment? Default: false (but true for CRAN submission checks).\n\n_R_CHECK_CODE_ATTACH_ ¶\n\nShould the package code be checked for calls to attach()? Default: false (but true for CRAN submission checks).\n\n_R_CHECK_CODE_DATA_INTO_GLOBALENV_ ¶\n\nShould the package code be checked for calls to data() which load into the global environment? Default: false (but true for CRAN submission checks).\n\n_R_CHECK_DOT_FIRSTLIB_ ¶\n\nShould the package code be checked for the presence of the obsolete function .First.lib()? Default: false (but true for CRAN submission checks).\n\n_R_CHECK_DEPRECATED_DEFUNCT_ ¶\n\nShould the package code be checked for the presence of recently deprecated or defunct functions (including completely removed functions). Also for platform-specific graphics devices. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_SCREEN_DEVICE_ ¶\n\nIf set to warn, give a warning if examples etc open a screen device. If set to stop, give an error. Default: empty (but stop for CRAN submission checks).\n\n_R_CHECK_WINDOWS_DEVICE_ ¶\n\nIf set to stop, give an error if a Windows-only device is used in example etc. This is only useful on Windows: the devices do not exist elsewhere. Default: empty (but stop for CRAN submission checks on Windows).\n\n_R_CHECK_TOPLEVEL_FILES_ ¶\n\nReport on top-level files in the package sources that are not described in ‘Writing R Extensions’ nor are commonly understood (like ChangeLog). Variations on standard names (e.g. COPYRIGHT) are also reported. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_GCT_N_ ¶\n\nShould the --use-gct use gctorture2(n) rather than gctorture(TRUE)? Use a positive integer to enable this. Default: 0.\n\n_R_CHECK_LIMIT_CORES_ ¶\n\nIf set, check the usage of too many cores in package parallel. If set to warn gives a warning, to false or FALSE the check is skipped, and any other non-empty value gives an error when more than 2 children are spawned. Default: unset (but TRUE for CRAN submission checks).\n\n_R_CHECK_CODE_USAGE_VIA_NAMESPACES_ ¶\n\nIf set, check code usage (via codetools) directly on the package namespace without loading and attaching the package and its suggests and enhances. Default: true (and true for CRAN submission checks).\n\n_R_CHECK_CODE_USAGE_WITH_ONLY_BASE_ATTACHED_ ¶\n\nIf set, check code usage (via codetools) with only the base package attached. Default: true.\n\n_R_CHECK_EXIT_ON_FIRST_ERROR_ ¶\n\nIf set to a true value, the check will exit on the first error. Default: false.\n\n_R_CHECK_OVERWRITE_REGISTERED_S3_METHODS_ ¶\n\nIf set to a true value, report already registered S3 methods in base/recommended packages which are overwritten when this package’s namespace is loaded. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_TESTS_NLINES_ ¶\n\nNumber of trailing lines of test output to reproduce in the log. If 0 all lines except the R preamble are reproduced. Default: 13.\n\n_R_CHECK_NATIVE_ROUTINE_REGISTRATION_ ¶\n\nIf set to a true value, report if the entry points to register native routines and to suppress dynamic search are not found in a package’s DLL. (NB: this requires system command nm to be on the PATH. On Windows, objdump.exe is first searched for in compiler toolchain specified via Makeconf (can be customized by environment variable BINPREF). If not found there, it must be on the PATH. On Unix this would be normal when using a package with compiled code (which are the only ones this checks), but Windows’ users should check. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_NO_STOP_ON_TEST_ERROR_ ¶\n\nIf set to a true value, do not stop running tests after first error (as if command line option --no-stop-on-test-error had been given). Default: false (but true for CRAN submission checks).\n\n_R_CHECK_PRAGMAS_ ¶\n\nRun additional checks on the pragmas in C/C++ source code and headers. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_COMPILATION_FLAGS_ ¶\n\nIf the package is installed and has C/C++/Fortran code, check the install log for non-portable flags (for example those added to src/Makevars during configuration). Currently -W flags are reported, except -Wall, -Wextra and -Weverything, and flags which appear to be attempts to suppress warnings are highlighted. See section ‘Writing portable packages’ in the ‘Writing R Extensions’ manual for the rationale of this check (and why even -Werror is unsafe).\nEnvironment variable _R_CHECK_COMPILATION_FLAGS_KNOWN_ can be set to a space-separated set of flags which come from the R build used for testing (flags such as -Wall and -Wextra are already known). For example, for CRAN builds of R >= 4.0.0 on macOS one could use\n_R_CHECK_COMPILATION_FLAGS_KNOWN_=\"-mmacosx-version-min=10.13\" \nDefault: unset.\n\n_R_CHECK_R_DEPENDS_ ¶\n\nCheck that any dependence on R is not on a recent patch-level version such as R (>= 3.3.3) since blocking installation of a package will also block its reverse dependencies. Possible values \"note\", \"warn\" and logical values (where currently true values are equivalent to \"note\"). Default: false (but \"warn\" for --as-cran).\n\n_R_CHECK_SERIALIZATION_ ¶\n\nCheck that serialized R objects in the package sources were serialized with version 2 and there is no dependence on R >= 3.5.0. (Version 3 is in use as from R 3.5.0 but should only be used when necessary.) Default: false (but true for CRAN submission checks).\n\n_R_CHECK_R_ON_PATH_ ¶\n\nThis checks if the package attempts to use R or Rscript from the path rather than that under test. It does so by putting scripts at the head of the path which print a message and fail. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_PACKAGES_USED_IN_TESTS_USE_SUBDIRS_ ¶\n\nIf set to a true value, also check the R code in common unit test subdirectories of tests for undeclared package dependencies. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_SHLIB_OPENMP_FLAGS_ ¶\n\nCheck correct and portable use of SHLIB_OPENMP_*FLAGS in src/Makevars (and similar). Default: false (but true for CRAN submission checks).\n\n_R_CHECK_CONNECTIONS_LEFT_OPEN_ ¶\n\nWhen checking examples, check for each example if connections are left open: if any are found, this is reported with a fatal error. NB: ‘connections’ includes most use of files and any parallel clusters which have not be stopped by stopCluster(). Default: false (but true for CRAN submission checks).\n\n_R_CHECK_FUTURE_FILE_TIMESTAMPS_ ¶\n\nCheck if any of the input files has a timestamp in the future (and to do so, checks that the system clock is correct to within 5 minutes). Default: false (but true for CRAN submission checks).\n\n_R_CHECK_LENGTH_1_CONDITION_ ¶\n\nNo longer in use: conditions of length greater than one in if or while statements are now an error.\n\n_R_CHECK_VIGNETTES_SKIP_RUN_MAYBE_ ¶\n\nShould running the R code in the vignettes be skipped if vignette outputs are to be rebuilt (which will involve running that code). Default: false (but true for CRAN checking)\n\n_R_CHECK_BUILD_VIGNETTES_SEPARATELY_ ¶\n\nPrior to R 3.6.0, re-building the vignette outputs was done in a single R session which allowed accidental reliance of one vignette on another (for example, in the loading of packages). The current default is to use a separate session for each vignette; this option allows testing the older behaviour, Default: true\n\n_R_CHECK_SYSTEM_CLOCK_ ¶\n\nAs part of the ‘checking for future file timestamps’ enabled by --as-cran, check the system clock against an external clock to catch errors such as the wrong day or even year. Not necessary on systems doing repeated checks. Default: true (but false for CRAN checking)\n\n_R_CHECK_AUTOCONF_ ¶\n\nFor packages with a configure file generated by GNU autoconf and either configure.ac or configure,.in, check that autoreconf can, if available, be run in a copy of the sources (this will detect missing source files and report autoconf warnings). Environment variable AUTORECONf controls the command used: it can give the full path to autoreconf (without spaces) and can include flags such as --warnings=obsolete (which is added for autoreconf version 2.68 or 2.69 and is the default for later versions). Default: false (but true for CRAN submission checks).\n\n_R_CHECK_DATALIST_ ¶\n\nCheck whether file data/datalist is out-of-date. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_THINGS_IN_CHECK_DIR_ ¶\n\nCheck and report at the end of the check run if files have been left in the check directory. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_THINGS_IN_TEMP_DIR_ ¶\n\nCheck and report at the end of tthe check run if files would have been left in the temporary directory (usually /tmp on a Unix-alike). It does this by setting the environment variable TEMPDIR to a subdirectory of the R session directory for the check process: if any files or directories are left there they are removed. Since some of these might be out of the user’s control, environment variable _R_CHECK_THINGS_IN_TEMP_DIR_EXCLUDE_ can specify an (extended regex) pattern of file paths not to be reported – CRAN uses ^ompi. for directories left behind by OpenMPI. There are rare instances where TEMPDIR is not respected and so files are left in /tmp (and not reported, but see the next item): one example is /tmp/boost_interprocess on some OSes. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_THINGS_IN_OTHER_DIRS_ ¶\n\nCheck and report at the end of the check run if new files or directories are created in a selected set of directories during the check run. (This is confined to files owned by the user running the check process.) Currently the directories monitored are the home directory, /tmp (excluding RtmpXXXXXX dirs), /dav/shm, ~/.cache (recursively) and ~/.local/share (recursively) or their equivalents on Windows and macOS (the directories in which the default settings for tools::R_user_dir() use a R subdirectory). Additional directories can be specified in environment variable _R_CHECK_THINGS_IN_OTHER_DIRS_XTRA_, separated by semicolons. Directories are reported with a trailing / on all platforms.\nEnvironment variable _R_CHECK_THINGS_IN_OTHER_DIRS_EXCLUDE_ can specify an (extended regex) pattern of file paths not to be reported – this should match absolute file paths with home represented by ~. For example, on a Linux system\n'^~/.cache/(mozilla/firefox|mesa_shader_cache)/'\nmatches cache directories used by Firefox and OpenGL (and their content). If the value starts with @ it is considered as a filepath which is read with each line treated as a pattern to be matched.\nNote that other processes (include check runs in parallel) may create new files in these directories which will get reported. However, this optional check is very useful for narrowing down possible packages which are leaving behind unexpected files. Default: false\n\n_R_CHECK_BASHISMS_ ¶\n\nCheck the top-level scripts configure (unless generated by autoconf) and cleanup for non-Bourne-shell code, using the Perl script checkbashisms if available. This includes reporting scripts using the non-portable #! /bin/bash. (Script checkbashisms is available in most Linux distributions in a package named either devscripts or devscripts-checkbashisms and from https://sourceforge.net/projects/checkbaskisms/files.) Default: false (but true for CRAN submission checks except on Windows).\n\n_R_CHECK_ORPHANED_ ¶\n\nCheck if dependencies are orphaned packages. As from R 4.1.0 this checks strict dependencies recursively, so will report any orphaned packages which are needed to attach the package by library() as well as any orphaned packages which are suggested. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_EXCESSIVE_IMPORTS_ ¶\n\nA positive integer. If set, give a NOTE if the number of imports from non-base packages exceed this threshold. Large numbers of imports make a package vulnerable to any of them becoming unavailable. Default: unset (but 20 for CRAN submission checks)\n\n_R_CHECK_DONTTEST_EXAMPLES_ ¶\n\nIf true and examples are found with \\donttest sections, the tests are run in one pass with these commented out and then in a second pass including the \\donttest sections, (for the main architecture only). Only for the first pass are the results compared to any .Rout.save file and timings analysed. Overridden by --run-donttest. Default: false unless --as-cran is specified (which can be overridden by setting _R_CHECK_DONTTEST_EXAMPLES_=false).\n\n_R_CHECK_XREFS_PKGS_ARE_DECLARED_ ¶\n\nCheck if packages used in ‘anchored’ cross-references in .Rd files (those of the form \\link[pkg]{foo} and \\link[pkg:bar]{foo}) are declared in the DESCRIPTION file and so these links can be checked. Default: false.\n\n_R_CHECK_XREFS_MIND_SUSPECT_ANCHORS_ ¶\n\nCheck if package-anchored Rd cross-references are to files (and not aliases). Default: false.\n\n_R_CHECK_BOGUS_RETURN_ ¶\n\nIf true and _R_CHECK_USE_CODETOOLS_ is also true, functions are scanned for use of return rather than return(). Default: false (but true for CRAN submission checks).\n\n_R_CHECK_MATRIX_DATA_ ¶\n\nBy default, the check for a mismatch between the data length and the dimensions in a call to matrix gives a warning: setting this to a true value gives an error with a compact traceback. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_CODE_CLASS_IS_STRING_ ¶\n\nCheck if package code has if() condition which compare the class of an object to a string. See https://blog.r-project.org/2019/11/09/when-you-think-class.-think-again/ why this is a bad idea. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_RD_VALIDATE_RD2HTML_ ¶\n\nCheck the validity of the package HTML help pages using HTML Tidy (https://www.html-tidy.org/) (if a suitable version is available on the system path for executables or its path is specified by environment variable R_TIDYCMD). macOS users are advised to install 5.8.0 or later from https://binaries.html-tidy.org/. Default: false (but true for CRAN submission checks). --as-cran can be overridden by setting this variable to a false value.\n\n_R_CHECK_RD_MATH_RENDERING_ ¶\n\nCheck whether HTML math rendering via KaTeX works (if package V8 is available). See https://blog.r-project.org/2022/04/08/enhancements-to-html-documentation/. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_NEWS_IN_PLAIN_TEXT_ ¶\n\nCheck whether news() can successfully read package news in plain text (file NEWS) format. Default: false (but true for CRAN submission checks).\n\n_R_WIN_CHECK_INVALID_PARAMETERS_ ¶\n\nCheck whether arguments passed to the Windows C runtime are valid. When enabled and a C runtime function is called with an invalid parameter, R prints diagnostic information and unconditionally terminates. By default, R for Windows following MinGW-W64 default causes UCRT to ignore invalid parameters, but they may cause R to abort e.g. when R is embedded into applications built with a different compiler toolchain. One may set the value to \"watson\" for interactive debugging on Windows via _invoke_watson. Default: disabled.\n\n_R_CHECK_BROWSER_NONINTERACTIVE_ ¶\n\nIf set to a true value, trap non-interactive debugger invocations. These are most likely caused by leftover browser() statements in package code. Default: unset (but true for CRAN submission checks).\n\n_R_CHECK_URLS_SHOW_301_STATUS_ ¶\n\nIf set to a true value, checking URLs show check status 301 for HTTP response status code “301 Moved Permanently”. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_UNDOC_USE_ALL_NAMES_ ¶\n\nIf set to a true value, checking for undocumented objects does not ignore objects with names starting with a dot (which prior to the advent of namespaces conventionally were considered as “internal”). Default: false (but true for CRAN submission checks).\n\n_R_CHECK_S3_METHODS_SHOW_POSSIBLE_ISSUES_ ¶\n\nDefault: false (but true for CRAN submission checks). If set to a true value, checking S3 methods also notes “possible issues”, including issues with apparent methods not registered and methods registered for non-generics. Default: false (but true for CRAN submission checks).\n\n_R_CHECK_MBCS_CONVERSION_FAILURE_ ¶\n\nIf set to a non-empty value, makes warnings from pdf() and postscript() about conversion failures from an MBCS (ususally UTF-8) into errors. Default: unset.\n\n\nThe following variables control checks for undeclared/unconditional use of other packages. They work by setting up a temporary library directory and setting .libPaths() to just that and .Library, so are only effective if additional packages are installed somewhere other than .Library. The temporary library is populated by symbolic links1 to installed packages not also in .Library.1 under Windows, junction points, or copies if environment variable R_WIN_NO_JUNCTIONS has a non-empty value.\n\n_R_CHECK_INSTALL_DEPENDS_ ¶\n\nIf set to a true value and a test installation is to be done, this is done with a temporary library populated by all the Depends/Imports/LinkingTo packages. Default: false (but true for CRAN submission checks).\nNote that this is actually implemented in R CMD INSTALL, so it is available to those who first install recording to a log, then call R CMD check.\n\n_R_CHECK_SUGGESTS_ONLY_ ¶\n\nIf set to a true value, running examples, tests and vignettes is done with a temporary library directory populated by all the Depends/Imports/Suggests packages. (As exceptions, packages in a VignetteBuilder field are always made available.) Default: false (but true for CRAN submission checks: some of the regular checks use true and some use false).\n\n_R_CHECK_DEPENDS_ONLY_ ¶\n\nAs for _R_CHECK_SUGGESTS_ONLY_ but using only Depends/Imports (and the exceptions, including test-suite managers in Suggests). Default: false\n\n_R_CHECK_DEPENDS_ONLY_DATA_ ¶\n\nApply _R_CHECK_DEPENDS_ONLY_ only to the check of loading from the data directory, so checks if any dataset depends on packages which are in Suggests or undeclared. Default: false (but true for CRAN submission checks)\n\n\n_R_CHECK_DEPENDS_ONLY_EXAMPLES_ ¶\n_R_CHECK_DEPENDS_ONLY_TESTS_ ¶\n_R_CHECK_DEPENDS_ONLY_VIGNETTES_ ¶\n: Apply _R_CHECK_DEPENDS_ONLY_ only to the checking of examples, tests or vignettes. These can be used on their own, or with a false value to override _R_CHECK_DEPENDS_ONLY_. Default: the value of _R_CHECK_DEPENDS_ONLY_ or false if that is unset.\n\n_R_CHECK_NO_RECOMMENDED_ ¶\n\nIf set to a true value, augment the previous checks to make recommended packages unavailable unless declared (even if installed in .Library). Default: false (but true for CRAN submission checks).\nThis may give false positives on code which uses grDevices::densCols and stats:::.asSparse / stats:::.Diag as these invoke KernSmooth and Matrix respectively. (Those in stats are called from various contrasts functions if sparse = TRUE is used.)\n\n\nCRAN’s submission checks use something like\n_R_CHECK_CRAN_INCOMING_=TRUE\n_R_CHECK_CRAN_INCOMING_REMOTE_=TRUE\n_R_CHECK_VC_DIRS_=TRUE\n_R_CHECK_TIMINGS_=10\n_R_CHECK_INSTALL_DEPENDS_=TRUE\n_R_CHECK_SUGGESTS_ONLY_=TRUE\n_R_CHECK_NO_RECOMMENDED_=TRUE\n_R_CHECK_EXECUTABLES_EXCLUSIONS_=FALSE\n_R_CHECK_DOC_SIZES2_=TRUE\n_R_CHECK_CODE_ASSIGN_TO_GLOBALENV_=TRUE\n_R_CHECK_CODE_ATTACH_=TRUE\n_R_CHECK_CODE_DATA_INTO_GLOBALENV_=TRUE\n_R_CHECK_CODE_USAGE_VIA_NAMESPACES_=TRUE\n_R_CHECK_DOT_FIRSTLIB_=TRUE\n_R_CHECK_DEPRECATED_DEFUNCT_=TRUE\n_R_CHECK_REPLACING_IMPORTS_=TRUE\n_R_CHECK_SCREEN_DEVICE_=stop\n_R_CHECK_TOPLEVEL_FILES_=TRUE\n_R_CHECK_OVERWRITE_REGISTERED_S3_METHODS_=TRUE\n_R_CHECK_PRAGMAS_=TRUE\n_R_CHECK_COMPILATION_FLAGS_=TRUE\n_R_CHECK_R_DEPENDS_=warn\n_R_CHECK_SERIALIZATION_=TRUE\n_R_CHECK_R_ON_PATH_=TRUE\n_R_CHECK_PACKAGES_USED_IN_TESTS_USE_SUBDIRS_=TRUE\n_R_CHECK_SHLIB_OPENMP_FLAGS_=TRUE\n_R_CHECK_CONNECTIONS_LEFT_OPEN_=TRUE\n_R_CHECK_FUTURE_FILE_TIMESTAMPS_=TRUE\n_R_CHECK_AUTOCONF_=true\n_R_CHECK_DATALIST_=true\n_R_CHECK_THINGS_IN_CHECK_DIR_=true\n_R_CHECK_THINGS_IN_TEMP_DIR_=true\n_R_CHECK_BASHISMS_=true\n_R_CHECK_ORPHANED_=true\n_R_CHECK_BOGUS_RETURN_=true\n_R_CHECK_MATRIX_DATA_=TRUE\n_R_CHECK_CODE_CLASS_IS_STRING_=true\n_R_CHECK_RD_VALIDATE_RD2HTML_=true\n_R_CHECK_RD_MATH_RENDERING_=true\n_R_CHECK_NEWS_IN_PLAIN_TEXT_=true\n_R_CHECK_BROWSER_NONINTERACTIVE_=true\n_R_CHECK_URLS_SHOW_301_STATUS_=true\n_R_CHECK_UNDOC_USE_ALL_NAMES_=true\n_R_CHECK_S3_METHODS_SHOW_POSSIBLE_ISSUES_=true\n_R_CHECK_RD_NOTE_LOST_BRACES_=true\nThese are turned on by R CMD check --as-cran: the incoming checks also use\n_R_CHECK_FORCE_SUGGESTS_=FALSE\nsince some packages do suggest other packages not available on CRAN or other commonly-used repositories.\nSeveral environment variables can be used to set ‘timeouts’: limits for the elapsed time taken by the sub-processes used for parts of the checks. A value of 0 indicates no limit, and is the default. Character strings ending in s, m or h indicate a number of seconds, minutes or hours respectively: other values are interpreted as a whole number of seconds (with invalid inputs being treated as no limit).\n\n_R_CHECK_ELAPSED_TIMEOUT_ ¶\n\nThe default timeout for sub-processes not otherwise mentioned, and the default value for all except _R_CHECK_ONE_TEST_ELAPSED_TIMEOUT_. (This is also used by tools::check_packages_in_dir.)\n\n_R_CHECK_INSTALL_ELAPSED_TIMEOUT_ ¶\n\nLimit for when R CMD INSTALL is run by check.\n\n_R_CHECK_EXAMPLES_ELAPSED_TIMEOUT_ ¶\n\nLimit for running all the examples for one sub-architecture.\n\n_R_CHECK_ONE_TEST_ELAPSED_TIMEOUT_ ¶\n\nLimit for running one test for one sub-architecture. Default _R_CHECK_TESTS_ELAPSED_TIMEOUT_.\n\n_R_CHECK_TESTS_ELAPSED_TIMEOUT_ ¶\n\nLimit for running all the tests for one sub-architecture (and the default limit for running one test).\n\n_R_CHECK_ONE_VIGNETTE_ELAPSED_TIMEOUT_ ¶\n\nLimit for running the R code in one vignette, including for re-building each vignette separately.\n\n_R_CHECK_BUILD_VIGNETTES_ELAPSED_TIMEOUT_ ¶\n\nLimit for re-building all vignettes.\n\n_R_CHECK_PKGMAN_ELAPSED_TIMEOUT_ ¶\n\nLimit for each attempt at building the PDF package manual.\n\n\nAnother variable which enables stricter checks is to set R_CHECK_CONSTANTS to 5. This checks that nothing2 changes the values of ‘constants’3 in R code. This is best used in conjunction with setting R_JIT_STRATEGY to 3, which checks code on first use (by default most code is only checked after byte-compilation on second use). Unfortunately these checks slow down checking of examples, tests and vignettes, typically two-fold but in the worst cases at least a hundred-fold.2 The usual culprits are calls to compiled code via .Call or .External which alter their arguments.3 things which the byte compiler assumes do not change, e.g. function bodies.\nThe following environment variables can be used to customize the operation of INSTALL.\n\n_R_INSTALL_LIBS_ONLY_FORCE_DEPENDS_IMPORTS_ ¶\n\nIf true, give an error if installing only package libraries via --libs-only and some package imported or depended on is not available. Default: true (false only for special applications, which analyze native code of packages).\n\n\nFootnotes" }, { "objectID": "R-coding-standards.html", @@ -298,7 +298,7 @@ "href": "Function-and-variable-index.html", "title": "Function and variable index", "section": "", - "text": "Jump to:  \n.   _  \nA   C   D   E   G   I   L   M   N   P   R   S   T   U   V   W  \n\n\n\n\n\n\n\nIndex Entry\n \nSection\n\n\n.\n\n\n\n\n\n\n.Device:\n \nBase environment\n\n\n\n.Devices:\n \nBase environment\n\n\n\n.Internal:\n \n.Internal vs .Primitive\n\n\n\n.Last.value:\n \nBase environment\n\n\n\n.Options:\n \nBase environment\n\n\n\n.Primitive:\n \n.Internal vs .Primitive\n\n\n\n.Random.seed:\n \nGlobal environment\n\n\n\n.SavedPlots:\n \nGlobal environment\n\n\n\n.Traceback:\n \nBase environment\n\n\n_\n\n\n\n\n\n\n_R_CHECK_ALL_NON_ISO_C_:\n \nTools\n\n\n\n_R_CHECK_ALWAYS_LOG_VIGNETTE_OUTPUT_:\n \nTools\n\n\n\n_R_CHECK_ASCII_CODE_:\n \nTools\n\n\n\n_R_CHECK_ASCII_DATA_:\n \nTools\n\n\n\n_R_CHECK_AUTOCONF_:\n \nTools\n\n\n\n_R_CHECK_BASHISMS_:\n \nTools\n\n\n\n_R_CHECK_BOGUS_RETURN_:\n \nTools\n\n\n\n_R_CHECK_BROWSER_NONINTERACTIVE_:\n \nTools\n\n\n\n_R_CHECK_BUILD_VIGNETTES_ELAPSED_TIMEOUT_:\n \nTools\n\n\n\n_R_CHECK_BUILD_VIGNETTES_SEPARATELY_:\n \nTools\n\n\n\n_R_CHECK_CLEAN_VIGN_TEST_:\n \nTools\n\n\n\n_R_CHECK_CODETOOLS_PROFILE_:\n \nTools\n\n\n\n_R_CHECK_CODE_ASSIGN_TO_GLOBALENV_:\n \nTools\n\n\n\n_R_CHECK_CODE_ATTACH_:\n \nTools\n\n\n\n_R_CHECK_CODE_CLASS_IS_STRING_:\n \nTools\n\n\n\n_R_CHECK_CODE_DATA_INTO_GLOBALENV_:\n \nTools\n\n\n\n_R_CHECK_CODE_USAGE_VIA_NAMESPACES_:\n \nTools\n\n\n\n_R_CHECK_CODE_USAGE_WITH_ONLY_BASE_ATTACHED_:\n \nTools\n\n\n\n_R_CHECK_CODOC_S4_METHODS_:\n \nTools\n\n\n\n_R_CHECK_COMPACT_DATA_:\n \nTools\n\n\n\n_R_CHECK_COMPILATION_FLAGS_:\n \nTools\n\n\n\n_R_CHECK_CONNECTIONS_LEFT_OPEN_:\n \nTools\n\n\n\n_R_CHECK_CRAN_INCOMING_:\n \nTools\n\n\n\n_R_CHECK_CRAN_INCOMING_REMOTE_:\n \nTools\n\n\n\n_R_CHECK_DATALIST_:\n \nTools\n\n\n\n_R_CHECK_DEPENDS_ONLY_:\n \nTools\n\n\n\n_R_CHECK_DEPENDS_ONLY_DATA_:\n \nTools\n\n\n\n_R_CHECK_DEPENDS_ONLY_EXAMPLES_:\n \nTools\n\n\n\n_R_CHECK_DEPENDS_ONLY_TESTS_:\n \nTools\n\n\n\n_R_CHECK_DEPENDS_ONLY_VIGNETTES_:\n \nTools\n\n\n\n_R_CHECK_DEPRECATED_DEFUNCT_:\n \nTools\n\n\n\n_R_CHECK_DOC_SIZES2_:\n \nTools\n\n\n\n_R_CHECK_DOC_SIZES_:\n \nTools\n\n\n\n_R_CHECK_DONTTEST_EXAMPLES_:\n \nTools\n\n\n\n_R_CHECK_DOT_FIRSTLIB_:\n \nTools\n\n\n\n_R_CHECK_DOT_INTERNAL_:\n \nTools\n\n\n\n_R_CHECK_ELAPSED_TIMEOUT_:\n \nTools\n\n\n\n_R_CHECK_EXAMPLES_ELAPSED_TIMEOUT_:\n \nTools\n\n\n\n_R_CHECK_EXAMPLE_TIMING_CPU_TO_ELAPSED_THRESHOLD_:\n \nTools\n\n\n\n_R_CHECK_EXAMPLE_TIMING_THRESHOLD_:\n \nTools\n\n\n\n_R_CHECK_EXCESSIVE_IMPORTS_:\n \nTools\n\n\n\n_R_CHECK_EXECUTABLES_:\n \nTools\n\n\n\n_R_CHECK_EXECUTABLES_EXCLUSIONS_:\n \nTools\n\n\n\n_R_CHECK_EXIT_ON_FIRST_ERROR_:\n \nTools\n\n\n\n_R_CHECK_FF_CALLS_:\n \nTools\n\n\n\n_R_CHECK_FF_DUP_:\n \nTools\n\n\n\n_R_CHECK_FORCE_SUGGESTS_:\n \nTools\n\n\n\n_R_CHECK_FUTURE_FILE_TIMESTAMPS_:\n \nTools\n\n\n\n_R_CHECK_GCT_N_:\n \nTools\n\n\n\n_R_CHECK_INSTALL_DEPENDS_:\n \nTools\n\n\n\n_R_CHECK_INSTALL_ELAPSED_TIMEOUT_:\n \nTools\n\n\n\n_R_CHECK_INSTALL_TIMING_CPU_TO_ELAPSED_THRESHOLD_:\n \nTools\n\n\n\n_R_CHECK_LENGTH_1_CONDITION_:\n \nTools\n\n\n\n_R_CHECK_LICENSE_:\n \nTools\n\n\n\n_R_CHECK_LIMIT_CORES_:\n \nTools\n\n\n\n_R_CHECK_MATRIX_DATA_:\n \nTools\n\n\n\n_R_CHECK_NATIVE_ROUTINE_REGISTRATION_:\n \nTools\n\n\n\n_R_CHECK_NEWS_IN_PLAIN_TEXT_:\n \nTools\n\n\n\n_R_CHECK_NO_RECOMMENDED_:\n \nTools\n\n\n\n_R_CHECK_NO_STOP_ON_TEST_ERROR_:\n \nTools\n\n\n\n_R_CHECK_ONE_TEST_ELAPSED_TIMEOUT_:\n \nTools\n\n\n\n_R_CHECK_ONE_VIGNETTE_ELAPSED_TIMEOUT_:\n \nTools\n\n\n\n_R_CHECK_ORPHANED_:\n \nTools\n\n\n\n_R_CHECK_OVERWRITE_REGISTERED_S3_METHODS_:\n \nTools\n\n\n\n_R_CHECK_PACKAGES_USED_IN_TESTS_USE_SUBDIRS_:\n \nTools\n\n\n\n_R_CHECK_PERMISSIONS_:\n \nTools\n\n\n\n_R_CHECK_PKGMAN_ELAPSED_TIMEOUT_:\n \nTools\n\n\n\n_R_CHECK_PKG_SIZES_:\n \nTools\n\n\n\n_R_CHECK_PKG_SIZES_THRESHOLD_:\n \nTools\n\n\n\n_R_CHECK_PRAGMAS_:\n \nTools\n\n\n\n_R_CHECK_RD_ALLOW_EMPTY_ITEM_IN_DESCRIBE_:\n \nTools\n\n\n\n_R_CHECK_RD_CHECKRD_MINLEVEL_:\n \nTools\n\n\n\n_R_CHECK_RD_CONTENTS_:\n \nTools\n\n\n\n_R_CHECK_RD_EXAMPLES_T_AND_F_:\n \nTools\n\n\n\n_R_CHECK_RD_LINE_WIDTHS_:\n \nTools\n\n\n\n_R_CHECK_RD_MATH_RENDERING_:\n \nTools\n\n\n\n_R_CHECK_RD_STYLE_:\n \nTools\n\n\n\n_R_CHECK_RD_VALIDATE_RD2HTML_:\n \nTools\n\n\n\n_R_CHECK_RD_XREFS_:\n \nTools\n\n\n\n_R_CHECK_REPLACING_IMPORTS_:\n \nTools\n\n\n\n_R_CHECK_R_DEPENDS_:\n \nTools\n\n\n\n_R_CHECK_R_ON_PATH_:\n \nTools\n\n\n\n_R_CHECK_S3_METHODS_SHOW_POSSIBLE_ISSUES_:\n \nTools\n\n\n\n_R_CHECK_SCREEN_DEVICE_:\n \nTools\n\n\n\n_R_CHECK_SERIALIZATION_:\n \nTools\n\n\n\n_R_CHECK_SHLIB_OPENMP_FLAGS_:\n \nTools\n\n\n\n_R_CHECK_SKIP_ARCH_:\n \nTools\n\n\n\n_R_CHECK_SKIP_EXAMPLES_ARCH_:\n \nTools\n\n\n\n_R_CHECK_SKIP_TESTS_ARCH_:\n \nTools\n\n\n\n_R_CHECK_SRC_MINUS_W_IMPLICIT_:\n \nTools\n\n\n\n_R_CHECK_SRC_MINUS_W_UNUSED_:\n \nTools\n\n\n\n_R_CHECK_SUBDIRS_NOCASE_:\n \nTools\n\n\n\n_R_CHECK_SUBDIRS_STRICT_:\n \nTools\n\n\n\n_R_CHECK_SUGGESTS_ONLY_:\n \nTools\n\n\n\n_R_CHECK_SYSTEM_CLOCK_:\n \nTools\n\n\n\n_R_CHECK_TESTS_ELAPSED_TIMEOUT_:\n \nTools\n\n\n\n_R_CHECK_TESTS_NLINES_:\n \nTools\n\n\n\n_R_CHECK_TEST_TIMING_CPU_TO_ELAPSED_THRESHOLD_:\n \nTools\n\n\n\n_R_CHECK_THINGS_IN_CHECK_DIR_:\n \nTools\n\n\n\n_R_CHECK_THINGS_IN_OTHER_DIRS_:\n \nTools\n\n\n\n_R_CHECK_THINGS_IN_TEMP_DIR_:\n \nTools\n\n\n\n_R_CHECK_TIMINGS_:\n \nTools\n\n\n\n_R_CHECK_TOPLEVEL_FILES_:\n \nTools\n\n\n\n_R_CHECK_UNDOC_USE_ALL_NAMES_:\n \nTools\n\n\n\n_R_CHECK_UNSAFE_CALLS_:\n \nTools\n\n\n\n_R_CHECK_URLS_SHOW_301_STATUS_:\n \nTools\n\n\n\n_R_CHECK_USE_CODETOOLS_:\n \nTools\n\n\n\n_R_CHECK_USE_INSTALL_LOG_:\n \nTools\n\n\n\n_R_CHECK_VC_DIRS_:\n \nTools\n\n\n\n_R_CHECK_VIGNETTES_NLINES_:\n \nTools\n\n\n\n_R_CHECK_VIGNETTES_SKIP_RUN_MAYBE_:\n \nTools\n\n\n\n_R_CHECK_VIGNETTE_TIMING_CPU_TO_ELAPSED_THRESHOLD_:\n \nTools\n\n\n\n_R_CHECK_WALL_FORTRAN_:\n \nTools\n\n\n\n_R_CHECK_WINDOWS_DEVICE_:\n \nTools\n\n\n\n_R_CHECK_XREFS_MIND_SUSPECT_ANCHORS_:\n \nTools\n\n\n\n_R_CHECK_XREFS_PKGS_ARE_DECLARED_:\n \nTools\n\n\n\n_R_CHECK_XREFS_REPOSITORIES_:\n \nTools\n\n\n\n_R_CHECK_XREFS_USE_ALIASES_FROM_CRAN_:\n \nTools\n\n\n\n_R_INSTALL_LIBS_ONLY_FORCE_DEPENDS_IMPORTS_:\n \nTools\n\n\n\n_R_SHLIB_BUILD_OBJECTS_SYMBOL_TABLES_:\n \nTools\n\n\n\n_R_WIN_CHECK_INVALID_PARAMETERS_:\n \nTools\n\n\nA\n\n\n\n\n\n\nalloca:\n \nMemory allocators\n\n\n\nARGSUSED:\n \nRest of header\n\n\n\nATTRIB:\n \nAttributes\n\n\n\nattribute_hidden:\n \nHiding C entry points\n\n\nC\n\n\n\n\n\n\ncopyMostAttrib:\n \nAttributes\n\n\nD\n\n\n\n\n\n\nDDVAL:\n \nRest of header\n\n\n\ndebug bit:\n \nRest of header\n\n\n\nDispatchGeneric:\n \nArgument evaluation\n\n\n\nDispatchOrEval:\n \nArgument evaluation\n\n\n\ndump.frames:\n \nGlobal environment\n\n\n\nDUPLICATE_ATTRIB:\n \nAttributes\n\n\nE\n\n\n\n\n\n\nemacs:\n \nR coding standards\n\n\n\nerror:\n \nWarnings and errors\n\n\n\nerrorcall:\n \nWarnings and errors\n\n\nG\n\n\n\n\n\n\ngp bits:\n \nRest of header\n\n\nI\n\n\n\n\n\n\ninvisible:\n \nAutoprinting\n\n\nL\n\n\n\n\n\n\nlast.warning:\n \nBase environment\n\n\n\nLEVELS:\n \nRest of header\n\n\nM\n\n\n\n\n\n\nmake:\n \nR coding standards\n\n\n\nmakeinfo:\n \nR coding standards\n\n\n\nMISSING:\n \nRest of header\n\n\n\nMISSING:\n \nMissingness\n\n\n\nmkChar:\n \nThe CHARSXP cache\n\n\n\nmkCharLenCE:\n \nThe CHARSXP cache\n\n\nN\n\n\n\n\n\n\nNAMED:\n \nRest of header\n\n\n\nNAMED:\n \nArgument evaluation\n\n\n\nNAMED:\n \n.Internal vs .Primitive\n\n\n\nnamed bits:\n \nRest of header\n\n\nP\n\n\n\n\n\n\nPerl:\n \nR coding standards\n\n\n\nPRIMPRINT:\n \nAutoprinting\n\n\n\nPRSEEN:\n \nRest of header\n\n\nR\n\n\n\n\n\n\nRdll.hide:\n \nHiding C entry points\n\n\n\nR_alloc:\n \nMemory allocators\n\n\n\nR_AllocStringBuffer:\n \nMemory allocators\n\n\n\nR_BaseNamespace:\n \nNamespaces\n\n\n\nR_Calloc:\n \nMemory allocators\n\n\n\nR_CheckStack:\n \nMemory allocators\n\n\n\nR_CheckStack2:\n \nMemory allocators\n\n\n\nR_Free:\n \nMemory allocators\n\n\n\nR_FreeStringBuffer:\n \nMemory allocators\n\n\n\nR_FreeStringBufferL:\n \nMemory allocators\n\n\n\nR_MissingArg:\n \nMissingness\n\n\n\nR_Realloc:\n \nMemory allocators\n\n\n\nR_Visible:\n \nAutoprinting\n\n\nS\n\n\n\n\n\n\nSETLEVELS:\n \nRest of header\n\n\n\nSET_ARGUSED:\n \nRest of header\n\n\n\nSET_ATTRIB:\n \nAttributes\n\n\n\nSET_DDVAL:\n \nRest of header\n\n\n\nSET_MISSING:\n \nRest of header\n\n\n\nSET_NAMED:\n \nRest of header\n\n\n\nspare bit:\n \nRest of header\n\n\nT\n\n\n\n\n\n\ntrace bit:\n \nRest of header\n\n\nU\n\n\n\n\n\n\nUseMethod:\n \nContexts\n\n\nV\n\n\n\n\n\n\nvmaxget:\n \nMemory allocators\n\n\n\nvmaxset:\n \nMemory allocators\n\n\nW\n\n\n\n\n\n\nwarning:\n \nWarnings and errors\n\n\n\nwarningcall:\n \nWarnings and errors\n\n\n\n\n\n\nJump to:  \n.   _  \nA   C   D   E   G   I   L   M   N   P   R   S   T   U   V   W" + "text": "Jump to:  \n.   _  \nA   C   D   E   G   I   L   M   N   P   R   S   T   U   V   W  \n\n\n\n\n\n\n\nIndex Entry\n \nSection\n\n\n.\n\n\n\n\n\n\n.Device:\n \nBase environment\n\n\n\n.Devices:\n \nBase environment\n\n\n\n.Internal:\n \n.Internal vs .Primitive\n\n\n\n.Last.value:\n \nBase environment\n\n\n\n.Options:\n \nBase environment\n\n\n\n.Primitive:\n \n.Internal vs .Primitive\n\n\n\n.Random.seed:\n \nGlobal environment\n\n\n\n.SavedPlots:\n \nGlobal environment\n\n\n\n.Traceback:\n \nBase environment\n\n\n_\n\n\n\n\n\n\n_R_CHECK_ALL_NON_ISO_C_:\n \nTools\n\n\n\n_R_CHECK_ALWAYS_LOG_VIGNETTE_OUTPUT_:\n \nTools\n\n\n\n_R_CHECK_ASCII_CODE_:\n \nTools\n\n\n\n_R_CHECK_ASCII_DATA_:\n \nTools\n\n\n\n_R_CHECK_AUTOCONF_:\n \nTools\n\n\n\n_R_CHECK_BASHISMS_:\n \nTools\n\n\n\n_R_CHECK_BOGUS_RETURN_:\n \nTools\n\n\n\n_R_CHECK_BROWSER_NONINTERACTIVE_:\n \nTools\n\n\n\n_R_CHECK_BUILD_VIGNETTES_ELAPSED_TIMEOUT_:\n \nTools\n\n\n\n_R_CHECK_BUILD_VIGNETTES_SEPARATELY_:\n \nTools\n\n\n\n_R_CHECK_CLEAN_VIGN_TEST_:\n \nTools\n\n\n\n_R_CHECK_CODETOOLS_PROFILE_:\n \nTools\n\n\n\n_R_CHECK_CODE_ASSIGN_TO_GLOBALENV_:\n \nTools\n\n\n\n_R_CHECK_CODE_ATTACH_:\n \nTools\n\n\n\n_R_CHECK_CODE_CLASS_IS_STRING_:\n \nTools\n\n\n\n_R_CHECK_CODE_DATA_INTO_GLOBALENV_:\n \nTools\n\n\n\n_R_CHECK_CODE_USAGE_VIA_NAMESPACES_:\n \nTools\n\n\n\n_R_CHECK_CODE_USAGE_WITH_ONLY_BASE_ATTACHED_:\n \nTools\n\n\n\n_R_CHECK_CODOC_S4_METHODS_:\n \nTools\n\n\n\n_R_CHECK_COMPACT_DATA_:\n \nTools\n\n\n\n_R_CHECK_COMPILATION_FLAGS_:\n \nTools\n\n\n\n_R_CHECK_CONNECTIONS_LEFT_OPEN_:\n \nTools\n\n\n\n_R_CHECK_CRAN_INCOMING_:\n \nTools\n\n\n\n_R_CHECK_CRAN_INCOMING_REMOTE_:\n \nTools\n\n\n\n_R_CHECK_DATALIST_:\n \nTools\n\n\n\n_R_CHECK_DEPENDS_ONLY_:\n \nTools\n\n\n\n_R_CHECK_DEPENDS_ONLY_DATA_:\n \nTools\n\n\n\n_R_CHECK_DEPENDS_ONLY_EXAMPLES_:\n \nTools\n\n\n\n_R_CHECK_DEPENDS_ONLY_TESTS_:\n \nTools\n\n\n\n_R_CHECK_DEPENDS_ONLY_VIGNETTES_:\n \nTools\n\n\n\n_R_CHECK_DEPRECATED_DEFUNCT_:\n \nTools\n\n\n\n_R_CHECK_DOC_SIZES2_:\n \nTools\n\n\n\n_R_CHECK_DOC_SIZES_:\n \nTools\n\n\n\n_R_CHECK_DONTTEST_EXAMPLES_:\n \nTools\n\n\n\n_R_CHECK_DOT_FIRSTLIB_:\n \nTools\n\n\n\n_R_CHECK_DOT_INTERNAL_:\n \nTools\n\n\n\n_R_CHECK_ELAPSED_TIMEOUT_:\n \nTools\n\n\n\n_R_CHECK_EXAMPLES_ELAPSED_TIMEOUT_:\n \nTools\n\n\n\n_R_CHECK_EXAMPLE_TIMING_CPU_TO_ELAPSED_THRESHOLD_:\n \nTools\n\n\n\n_R_CHECK_EXAMPLE_TIMING_THRESHOLD_:\n \nTools\n\n\n\n_R_CHECK_EXCESSIVE_IMPORTS_:\n \nTools\n\n\n\n_R_CHECK_EXECUTABLES_:\n \nTools\n\n\n\n_R_CHECK_EXECUTABLES_EXCLUSIONS_:\n \nTools\n\n\n\n_R_CHECK_EXIT_ON_FIRST_ERROR_:\n \nTools\n\n\n\n_R_CHECK_FF_CALLS_:\n \nTools\n\n\n\n_R_CHECK_FF_DUP_:\n \nTools\n\n\n\n_R_CHECK_FORCE_SUGGESTS_:\n \nTools\n\n\n\n_R_CHECK_FUTURE_FILE_TIMESTAMPS_:\n \nTools\n\n\n\n_R_CHECK_GCT_N_:\n \nTools\n\n\n\n_R_CHECK_INSTALL_DEPENDS_:\n \nTools\n\n\n\n_R_CHECK_INSTALL_ELAPSED_TIMEOUT_:\n \nTools\n\n\n\n_R_CHECK_INSTALL_TIMING_CPU_TO_ELAPSED_THRESHOLD_:\n \nTools\n\n\n\n_R_CHECK_LENGTH_1_CONDITION_:\n \nTools\n\n\n\n_R_CHECK_LICENSE_:\n \nTools\n\n\n\n_R_CHECK_LIMIT_CORES_:\n \nTools\n\n\n\n_R_CHECK_MATRIX_DATA_:\n \nTools\n\n\n\n_R_CHECK_MBCS_CONVERSION_FAILURE_:\n \nTools\n\n\n\n_R_CHECK_NATIVE_ROUTINE_REGISTRATION_:\n \nTools\n\n\n\n_R_CHECK_NEWS_IN_PLAIN_TEXT_:\n \nTools\n\n\n\n_R_CHECK_NO_RECOMMENDED_:\n \nTools\n\n\n\n_R_CHECK_NO_STOP_ON_TEST_ERROR_:\n \nTools\n\n\n\n_R_CHECK_ONE_TEST_ELAPSED_TIMEOUT_:\n \nTools\n\n\n\n_R_CHECK_ONE_VIGNETTE_ELAPSED_TIMEOUT_:\n \nTools\n\n\n\n_R_CHECK_ORPHANED_:\n \nTools\n\n\n\n_R_CHECK_OVERWRITE_REGISTERED_S3_METHODS_:\n \nTools\n\n\n\n_R_CHECK_PACKAGES_USED_IN_TESTS_USE_SUBDIRS_:\n \nTools\n\n\n\n_R_CHECK_PERMISSIONS_:\n \nTools\n\n\n\n_R_CHECK_PKGMAN_ELAPSED_TIMEOUT_:\n \nTools\n\n\n\n_R_CHECK_PKG_SIZES_:\n \nTools\n\n\n\n_R_CHECK_PKG_SIZES_THRESHOLD_:\n \nTools\n\n\n\n_R_CHECK_PRAGMAS_:\n \nTools\n\n\n\n_R_CHECK_RD_ALLOW_EMPTY_ITEM_IN_DESCRIBE_:\n \nTools\n\n\n\n_R_CHECK_RD_CHECKRD_MINLEVEL_:\n \nTools\n\n\n\n_R_CHECK_RD_CONTENTS_:\n \nTools\n\n\n\n_R_CHECK_RD_EXAMPLES_T_AND_F_:\n \nTools\n\n\n\n_R_CHECK_RD_LINE_WIDTHS_:\n \nTools\n\n\n\n_R_CHECK_RD_MATH_RENDERING_:\n \nTools\n\n\n\n_R_CHECK_RD_NOTE_LOST_BRACES_:\n \nTools\n\n\n\n_R_CHECK_RD_STYLE_:\n \nTools\n\n\n\n_R_CHECK_RD_VALIDATE_RD2HTML_:\n \nTools\n\n\n\n_R_CHECK_RD_XREFS_:\n \nTools\n\n\n\n_R_CHECK_REPLACING_IMPORTS_:\n \nTools\n\n\n\n_R_CHECK_R_DEPENDS_:\n \nTools\n\n\n\n_R_CHECK_R_ON_PATH_:\n \nTools\n\n\n\n_R_CHECK_S3_METHODS_SHOW_POSSIBLE_ISSUES_:\n \nTools\n\n\n\n_R_CHECK_SCREEN_DEVICE_:\n \nTools\n\n\n\n_R_CHECK_SERIALIZATION_:\n \nTools\n\n\n\n_R_CHECK_SHLIB_OPENMP_FLAGS_:\n \nTools\n\n\n\n_R_CHECK_SKIP_ARCH_:\n \nTools\n\n\n\n_R_CHECK_SKIP_EXAMPLES_ARCH_:\n \nTools\n\n\n\n_R_CHECK_SKIP_TESTS_ARCH_:\n \nTools\n\n\n\n_R_CHECK_SRC_MINUS_W_IMPLICIT_:\n \nTools\n\n\n\n_R_CHECK_SRC_MINUS_W_UNUSED_:\n \nTools\n\n\n\n_R_CHECK_SUBDIRS_NOCASE_:\n \nTools\n\n\n\n_R_CHECK_SUBDIRS_STRICT_:\n \nTools\n\n\n\n_R_CHECK_SUGGESTS_ONLY_:\n \nTools\n\n\n\n_R_CHECK_SYSTEM_CLOCK_:\n \nTools\n\n\n\n_R_CHECK_TESTS_ELAPSED_TIMEOUT_:\n \nTools\n\n\n\n_R_CHECK_TESTS_NLINES_:\n \nTools\n\n\n\n_R_CHECK_TEST_TIMING_CPU_TO_ELAPSED_THRESHOLD_:\n \nTools\n\n\n\n_R_CHECK_THINGS_IN_CHECK_DIR_:\n \nTools\n\n\n\n_R_CHECK_THINGS_IN_OTHER_DIRS_:\n \nTools\n\n\n\n_R_CHECK_THINGS_IN_TEMP_DIR_:\n \nTools\n\n\n\n_R_CHECK_TIMINGS_:\n \nTools\n\n\n\n_R_CHECK_TOPLEVEL_FILES_:\n \nTools\n\n\n\n_R_CHECK_UNDOC_USE_ALL_NAMES_:\n \nTools\n\n\n\n_R_CHECK_UNSAFE_CALLS_:\n \nTools\n\n\n\n_R_CHECK_URLS_SHOW_301_STATUS_:\n \nTools\n\n\n\n_R_CHECK_USE_CODETOOLS_:\n \nTools\n\n\n\n_R_CHECK_USE_INSTALL_LOG_:\n \nTools\n\n\n\n_R_CHECK_VC_DIRS_:\n \nTools\n\n\n\n_R_CHECK_VIGNETTES_NLINES_:\n \nTools\n\n\n\n_R_CHECK_VIGNETTES_SKIP_RUN_MAYBE_:\n \nTools\n\n\n\n_R_CHECK_VIGNETTE_TIMING_CPU_TO_ELAPSED_THRESHOLD_:\n \nTools\n\n\n\n_R_CHECK_WALL_FORTRAN_:\n \nTools\n\n\n\n_R_CHECK_WINDOWS_DEVICE_:\n \nTools\n\n\n\n_R_CHECK_XREFS_MIND_SUSPECT_ANCHORS_:\n \nTools\n\n\n\n_R_CHECK_XREFS_PKGS_ARE_DECLARED_:\n \nTools\n\n\n\n_R_CHECK_XREFS_REPOSITORIES_:\n \nTools\n\n\n\n_R_CHECK_XREFS_USE_ALIASES_FROM_CRAN_:\n \nTools\n\n\n\n_R_INSTALL_LIBS_ONLY_FORCE_DEPENDS_IMPORTS_:\n \nTools\n\n\n\n_R_SHLIB_BUILD_OBJECTS_SYMBOL_TABLES_:\n \nTools\n\n\n\n_R_WIN_CHECK_INVALID_PARAMETERS_:\n \nTools\n\n\nA\n\n\n\n\n\n\nalloca:\n \nMemory allocators\n\n\n\nARGSUSED:\n \nRest of header\n\n\n\nATTRIB:\n \nAttributes\n\n\n\nattribute_hidden:\n \nHiding C entry points\n\n\nC\n\n\n\n\n\n\ncopyMostAttrib:\n \nAttributes\n\n\nD\n\n\n\n\n\n\nDDVAL:\n \nRest of header\n\n\n\ndebug bit:\n \nRest of header\n\n\n\nDispatchGeneric:\n \nArgument evaluation\n\n\n\nDispatchOrEval:\n \nArgument evaluation\n\n\n\ndump.frames:\n \nGlobal environment\n\n\n\nDUPLICATE_ATTRIB:\n \nAttributes\n\n\nE\n\n\n\n\n\n\nemacs:\n \nR coding standards\n\n\n\nerror:\n \nWarnings and errors\n\n\n\nerrorcall:\n \nWarnings and errors\n\n\nG\n\n\n\n\n\n\ngp bits:\n \nRest of header\n\n\nI\n\n\n\n\n\n\ninvisible:\n \nAutoprinting\n\n\nL\n\n\n\n\n\n\nlast.warning:\n \nBase environment\n\n\n\nLEVELS:\n \nRest of header\n\n\nM\n\n\n\n\n\n\nmake:\n \nR coding standards\n\n\n\nmakeinfo:\n \nR coding standards\n\n\n\nMISSING:\n \nRest of header\n\n\n\nMISSING:\n \nMissingness\n\n\n\nmkChar:\n \nThe CHARSXP cache\n\n\n\nmkCharLenCE:\n \nThe CHARSXP cache\n\n\nN\n\n\n\n\n\n\nNAMED:\n \nRest of header\n\n\n\nNAMED:\n \nArgument evaluation\n\n\n\nNAMED:\n \n.Internal vs .Primitive\n\n\n\nnamed bits:\n \nRest of header\n\n\nP\n\n\n\n\n\n\nPerl:\n \nR coding standards\n\n\n\nPRIMPRINT:\n \nAutoprinting\n\n\n\nPRSEEN:\n \nRest of header\n\n\nR\n\n\n\n\n\n\nRdll.hide:\n \nHiding C entry points\n\n\n\nR_alloc:\n \nMemory allocators\n\n\n\nR_AllocStringBuffer:\n \nMemory allocators\n\n\n\nR_BaseNamespace:\n \nNamespaces\n\n\n\nR_Calloc:\n \nMemory allocators\n\n\n\nR_CheckStack:\n \nMemory allocators\n\n\n\nR_CheckStack2:\n \nMemory allocators\n\n\n\nR_Free:\n \nMemory allocators\n\n\n\nR_FreeStringBuffer:\n \nMemory allocators\n\n\n\nR_FreeStringBufferL:\n \nMemory allocators\n\n\n\nR_MissingArg:\n \nMissingness\n\n\n\nR_Realloc:\n \nMemory allocators\n\n\n\nR_Visible:\n \nAutoprinting\n\n\nS\n\n\n\n\n\n\nSETLEVELS:\n \nRest of header\n\n\n\nSET_ARGUSED:\n \nRest of header\n\n\n\nSET_ATTRIB:\n \nAttributes\n\n\n\nSET_DDVAL:\n \nRest of header\n\n\n\nSET_MISSING:\n \nRest of header\n\n\n\nSET_NAMED:\n \nRest of header\n\n\n\nspare bit:\n \nRest of header\n\n\nT\n\n\n\n\n\n\ntrace bit:\n \nRest of header\n\n\nU\n\n\n\n\n\n\nUseMethod:\n \nContexts\n\n\nV\n\n\n\n\n\n\nvmaxget:\n \nMemory allocators\n\n\n\nvmaxset:\n \nMemory allocators\n\n\nW\n\n\n\n\n\n\nwarning:\n \nWarnings and errors\n\n\n\nwarningcall:\n \nWarnings and errors\n\n\n\n\n\n\nJump to:  \n.   _  \nA   C   D   E   G   I   L   M   N   P   R   S   T   U   V   W" }, { "objectID": "Concept-index.html",