Title: | Friendly R Startup Configuration |
---|---|
Description: | Adds support for R startup configuration via '.Renviron.d' and '.Rprofile.d' directories in addition to '.Renviron' and '.Rprofile' files. This makes it possible to keep private / secret environment variables separate from other environment variables. It also makes it easier to share specific startup settings by simply copying a file to a directory. |
Authors: | Henrik Bengtsson [aut, cre, cph] |
Maintainer: | Henrik Bengtsson <[email protected]> |
License: | LGPL (>= 2.1) |
Version: | 0.23.0 |
Built: | 2024-12-08 01:35:10 UTC |
Source: | https://github.com/HenrikBengtsson/startup |
Check for and fix common mistakes in ‘.Rprofile’ files.
check(all = FALSE, fix = TRUE, backup = TRUE, debug = FALSE)
check(all = FALSE, fix = TRUE, backup = TRUE, debug = FALSE)
all |
Should all or only the first entry on the R startup search path be checked? |
fix |
If |
backup |
If |
debug |
If |
Returns invisibly a character vector of files that were "fixed"
(modified), if any. If no files needed to be fixed, or fix = TRUE
,
then an empty vector is returned.
R-devel thread 'Last line in .Rprofile must have newline (PR#4056)', 2003-09-03, https://stat.ethz.ch/pipermail/r-devel/2003-September/027457.html
Gets the pathname of the currently running startup script
current_script()
current_script()
A character string
Install and uninstall support for ‘.Renviron.d’ and ‘.Rprofile.d’ startup directories by appending / removing one line of code to the ‘~/.Rprofile’ file.
install( file = rprofile_user(), backup = TRUE, overwrite = FALSE, path = dirname(file), make_dirs = TRUE, quiet = FALSE ) uninstall(file = rprofile_user(), backup = TRUE, quiet = FALSE)
install( file = rprofile_user(), backup = TRUE, overwrite = FALSE, path = dirname(file), make_dirs = TRUE, quiet = FALSE ) uninstall(file = rprofile_user(), backup = TRUE, quiet = FALSE)
file |
The pathname where to create or update the ‘.Rprofile’ file. |
backup |
If |
overwrite |
If the R startup file already exist, then |
path |
The folder where to create ‘.Renviron.d’ and ‘.Rprofile.d’ directory. |
make_dirs |
If |
quiet |
If |
The pathname of the R startup file modified.
install()
: injects a tryCatch(startup::startup(), ...)
call to
the ‘.Rprofile’ file, which is created if missing.
uninstall()
: Remove calls to startup::startup()
and similar.
Checks if running R via Ark (An R Kernel)
is_ark()
is_ark()
A logical
Check if running R via Emacs Speaks Statistics (ESS)
is_ess()
is_ess()
A logical
Checks if running R via Jupyter
is_jupyter()
is_jupyter()
A logical
Check if running R via Microsoft R Open
is_microsoftr()
is_microsoftr()
A logical
Checks if running R via Positron
is_positron()
is_positron()
A logical
Check if running a Pretty Quick Version of R (pqR)
is_pqr()
is_pqr()
A logical
pqR - a pretty quick version of R, http://www.pqr-project.org/
GitHub repository for 'pqR' https://github.com/radfordneal/pqR
Check if running R via radian (formerly known as rtichoke and rice)
is_radian()
is_radian()
A logical
radian - A 21 century R console (previously known as rtichoke and rice), https://github.com/randy3k/radian
Checks if running R in RStudio Console or RStudio Terminal
is_rstudio_console()
is_rstudio_console()
A logical
Kevin Ushey (RStudio), Check if R is running in RStudio, Stackoverflow, 2016-09-23, https://stackoverflow.com/questions/12389158/check-if-r-is-running-in-rstudio#comment66636507_35849779
Jonathan McPherson (RStudio), Programmatically detect RStudio Terminal vs RStudio Console?, RStudio Community - RStudio IDE, 2018-01-10, https://forum.posit.co/t/programmatically-detect-rstudio-terminal-vs-rstudio-console/4107
Checks if running R via Visual Studio Code (VSCode)
is_vscode()
is_vscode()
A logical
Checks if running R via webR
is_webr()
is_webr()
A logical
webR - R in the Browser, https://docs.r-wasm.org/webr/latest/
Check if running R on Windows using Wine
is_wine()
is_wine()
A logical
Wine Developer FAQ, How can I detect Wine?, https://gitlab.winehq.org/wine/wine/-/wikis/Developer-FAQ#How_can_I_detect_Wine.3F
Jeff Zaroyko, Detecting Wine, Wine Devel mailing list, 2008-09-29, https://list.winehq.org/mailman3/hyperkitty/list/[email protected]/thread/TVQIRXMLJZYTTCMABIIVG7VIP46TQLLX/
Register functions to be evaluated at the beginning or end of the R session
on_session_enter(fcn = NULL, append = TRUE, replace = FALSE) on_session_exit(fcn = NULL, append = TRUE, replace = FALSE)
on_session_enter(fcn = NULL, append = TRUE, replace = FALSE) on_session_exit(fcn = NULL, append = TRUE, replace = FALSE)
fcn |
A function or an R expression. The function must accept zero or more arguments (currently not used). If an expression, it will automatically we wrapped up in an anonymous function. |
append |
If TRUE (default), the function will be evaluated after previously registered ones, otherwise prepended. |
replace |
if TRUE, the function replaces any previously registered ones, otherwise it will be added (default). |
These functions register one or more functions to be called when the current R session begins or ends. The functions are evaluated in a local environment and without exception handlers, which means that if one produces an error, then none of the succeeding functions will be called.
To list currently registered functions, use fcns <- on_session_enter()
or fcns <- on_session_exit()
.
To remove all registered functions, use on_session_enter(replace = TRUE)
or on_session_exit(replace = TRUE)
.
The on_session_enter()
function works by recording all fcn
:s in an
internal list which will be evaluated via a custom
.First()
function created in the global
environment. Any other .First()
function on the search path, including
a pre-existing .First()
function in the global environment, is called
at the end after registered functions have been called.
The on_session_exit()
function works by recording all fcn
:s in an
internal list which will be evaluated via a custom function that is called
when the global environment is garbage collected, which happens at the very
end of the R shutdown process.
Contrary to a .Last()
function, which is not be
called if quit(runLast = FALSE)
is used, functions registered via
on_session_exit()
are always processed.
Registered on_session_exit()
functions are called after quit()
saves
any workspace image to file (./.RData
), and after any .Last()
has
been called.
(invisible) the list of registered functions.
## Not run: ## Summarize interactive session upon termination if (interactive()) { startup::on_session_exit(local({ t0 <- Sys.time() function(...) { dt <- difftime(Sys.time(), t0, units = "auto") msg <- c( "Session summary:", sprintf(" * R version: %s", getRversion()), sprintf(" * Process ID: %d", Sys.getpid()), sprintf(" * Wall time: %.2f %s", dt, attr(dt, "units")) ) msg <- paste(msg, collapse = "\n") message(msg) } })) } ## End(Not run)
## Not run: ## Summarize interactive session upon termination if (interactive()) { startup::on_session_exit(local({ t0 <- Sys.time() function(...) { dt <- difftime(Sys.time(), t0, units = "auto") msg <- c( "Session summary:", sprintf(" * R version: %s", getRversion()), sprintf(" * Process ID: %d", Sys.getpid()), sprintf(" * Wall time: %.2f %s", dt, attr(dt, "units")) ) msg <- paste(msg, collapse = "\n") message(msg) } })) } ## End(Not run)
Initiates R using all files under ‘.Renviron.d/’ and / or ‘.Rprofile.d/’ directories (or in subdirectories thereof).
renviron_d( sibling = FALSE, all = FALSE, unload = FALSE, skip = NA, dryrun = NA, debug = NA, paths = NULL ) rprofile_d( sibling = FALSE, all = FALSE, check = NA, unload = FALSE, skip = NA, on_error = c("error", "warning", "immediate.warning", "message", "ignore"), dryrun = NA, debug = NA, paths = NULL ) startup( sibling = FALSE, all = FALSE, on_error = c("error", "warning", "immediate.warning", "message", "ignore"), keep = c("options"), check = NA, unload = TRUE, skip = NA, encoding = getOption("encoding"), dryrun = NA, debug = dryrun )
renviron_d( sibling = FALSE, all = FALSE, unload = FALSE, skip = NA, dryrun = NA, debug = NA, paths = NULL ) rprofile_d( sibling = FALSE, all = FALSE, check = NA, unload = FALSE, skip = NA, on_error = c("error", "warning", "immediate.warning", "message", "ignore"), dryrun = NA, debug = NA, paths = NULL ) startup( sibling = FALSE, all = FALSE, on_error = c("error", "warning", "immediate.warning", "message", "ignore"), keep = c("options"), check = NA, unload = TRUE, skip = NA, encoding = getOption("encoding"), dryrun = NA, debug = dryrun )
sibling |
If |
all |
If |
unload |
If |
skip |
If |
dryrun |
If |
debug |
If |
paths |
(internal) character vector of directories. |
check |
If |
on_error |
Action taken when an error is detected when sourcing an Rprofile file. It is not possible to detect error in Renviron files; they are always ignored with a message that cannot be captured. |
keep |
Specify what information should remain after this function
complete. The default is to keep |
encoding |
The encodingto use when parsing the R startup files.
See |
The above is done in addition the ‘.Renviron’ and ‘.Rprofile’ files that are supported by the built-in startup process of R.
renviron_d()
: Initiate using ‘.Renviron.d/’ files
rprofile_d()
: Initiate using ‘.Rprofile.d/’ files
startup()
: renviron_d()
followed by rprofile_d()
and then the
package is unloaded
In order for ‘.Rprofile.d’ and ‘.Renviron.d’ directories to be
included during the R startup process, a user needs to add
startup::startup()
to ‘~/.Rprofile’. Adding this can also be done
by calling install()
once.
An alternative to having each user add startup::startup()
in their own
‘~/.Rprofile’ file, is to add it to the site-wide ‘Rprofile.site’
file (see ?Startup).
The advantage of such a site-wide installation, is that the users do not
have to have a ‘.Rprofile’ file for ‘.Rprofile.d’ and
‘.Renviron.d’ directories to work.
For this to work for all users automatically, the startup package
should also be installed in the site-wide library.
## Not run: # The most common way to use the package is to add # the following call to the ~/.Rprofile file. startup::startup() # To process ~/.Renviron.d/ files, and then any ./.Renviron.d/ files, # followed by ~/.Rprofile.d/ files, and then any ./.Rprofile.d/ files, # add the following call to the ~/.Rprofile file. startup::startup(all = TRUE) # For finer control of on exactly what files are used # functions renviron_d() and rprofile_d() are also available: # Initiate first .Renviron.d/ found on search path startup::renviron_d() # Initiate all .Rprofile.d/ directories found on the startup search path startup::rprofile_d(all = TRUE) ## End(Not run)
## Not run: # The most common way to use the package is to add # the following call to the ~/.Rprofile file. startup::startup() # To process ~/.Renviron.d/ files, and then any ./.Renviron.d/ files, # followed by ~/.Rprofile.d/ files, and then any ./.Rprofile.d/ files, # add the following call to the ~/.Rprofile file. startup::startup(all = TRUE) # For finer control of on exactly what files are used # functions renviron_d() and rprofile_d() are also available: # Initiate first .Renviron.d/ found on search path startup::renviron_d() # Initiate all .Rprofile.d/ directories found on the startup search path startup::rprofile_d(all = TRUE) ## End(Not run)
Reset all or parts of the "when" cache
reset_when_cache( when = c("once", "hourly", "daily", "weekly", "fortnightly", "monthly") )
reset_when_cache( when = c("once", "hourly", "daily", "weekly", "fortnightly", "monthly") )
when |
(character vector) Specifies for which "when" frequencies the cache should be reset. The default is to reset all of them. |
(invisible) The pathnames of the "when" cache files removed.
Restarts R by quitting the current R session and launching a new one.
restart( status = 0L, workdir = NULL, rcmd = NULL, args = NULL, envvars = NULL, as = c("current", "specified", "R CMD build", "R CMD check", "R CMD INSTALL"), quiet = FALSE, debug = NA )
restart( status = 0L, workdir = NULL, rcmd = NULL, args = NULL, envvars = NULL, as = c("current", "specified", "R CMD build", "R CMD check", "R CMD INSTALL"), quiet = FALSE, debug = NA )
status |
An integer specifying the exit code of the current R session. |
workdir |
The working directory where the new R session should
be launched from. If |
rcmd |
A character string specifying the command for launching R.
The default is the same as used to launch the current R session, i.e.
|
args |
A character vector specifying zero or more command-line
arguments to be appended to the system call of |
envvars |
A named character vector of environment variables to be set when calling R. |
as |
A character string specifying a predefined setups of |
quiet |
Should the restart be quiet or not?
If |
debug |
If |
Argument as
may take the following values:
"current"
:(Default) A setup that emulates the setup of the
current R session as far as possible by relaunching R with the same
command-line call (= base::commandArgs()
).
"specified"
:According to rcmd
, args
, and envvars
.
"R CMD build"
:A setup that emulates
R CMD build
as far as possible.
"R CMD check"
:A setup that emulates
R CMD check
as far as possible, which happens to be identical to the
"R CMD build"
setup.
"R CMD INSTALL"
:A setup that emulates
R CMD INSTALL
as far as possible.
If specified, command-line arguments in args
and environment variables
in envvars
are appended accordingly.
It is not possible to restart an R session running in RGui on Microsoft Windows using this function.
It is not possible to restart an R session in the RStudio Console using this function. However, it does work when running R in the RStudio Terminal.
RStudio provides rstudioapi::restartSession()
which will indeed restart
the RStudio Console. However, it does not let you control how R is
restarted, e.g. with what command-line options and what environment
variables. Importantly, the new R session will have the same set of
packages loaded as before, the same variables in the global environment,
and so on.
## Not run: ## Relaunch R with debugging of startup::startup() enabled startup::restart(envvars = c(R_STARTUP_DEBUG = TRUE)) ## Relaunch R without loading user Rprofile files startup::restart(args = "--no-init-file") ## Mimic 'R CMD build' and 'R CMD check' startup::restart(as = "R CMD build") startup::restart(as = "R CMD check") ## ... which are both short for startup::restart(args = c("--no-restore"), envvars = c(R_DEFAULT_PACKAGES="", LC_COLLATE="C")) ## End(Not run)
## Not run: ## Relaunch R with debugging of startup::startup() enabled startup::restart(envvars = c(R_STARTUP_DEBUG = TRUE)) ## Relaunch R without loading user Rprofile files startup::restart(args = "--no-init-file") ## Mimic 'R CMD build' and 'R CMD check' startup::restart(as = "R CMD build") startup::restart(as = "R CMD check") ## ... which are both short for startup::restart(args = c("--no-restore"), envvars = c(R_DEFAULT_PACKAGES="", LC_COLLATE="C")) ## End(Not run)
Record R session information as options
startup_session_options(action = c("update", "overwrite", "erase"))
startup_session_options(action = c("update", "overwrite", "erase"))
action |
If |
Returns invisibly a named list of the options prefixed
"startup.session."
:
startup.session.startdir
(character) the working directory when
the startup was first loaded. If startup::startup()
is called
at the very beginning of the ‘.Rprofile’ file, this is also the
directory that the current R session was launched from.
startup.session.starttime
(POSIXct) the time when the startup was first loaded.
startup.session.id
(character) a unique ID for the current R session.
startup.session.dumpto
(character) a session-specific name that
can be used for argument dumpto
of dump.frames()
(also for dumping to file).
opts <- startup::startup_session_options() opts
opts <- startup::startup_session_options() opts
Below are environment variables and R options that are used by the
startup package.
The R_STARTUP_*** environment variables must be set before calling
the startup::startup()
function, that is, either (i) prior to launching
R or (ii) in the ‘.Renviron’ file.
(logical)
If TRUE
, startup::startup()
is fully disable such that no
‘.Renviron.d/’ or ‘.Rprofile.d/’ files are processed.
Note: Files ‘.Renviron’ and ‘.Rprofile’ are still processed
because these are out of control of the startup package.
(Default: FALSE
)
(logical)
Controls the default value of argument dryrun
of startup()
.
(Default: FALSE
)
(R script as a character string)
Optional R script that is parsed and evaluated after
‘.Renviron.d/’ and ‘.Rprofile.d/’ files,
and R_STARTUP_INIT
code, have been processed, e.g.
R_STARTUP_FILE="setup.R" R --quiet
.
(Default: not specified)
(R code as a character string)
Optional R code that is parsed and evaluated after
‘.Renviron.d/’ and ‘.Rprofile.d/’ files,
but before R_STARTUP_FILE
code, have been processed e.g.
R_STARTUP_INIT="message('Hello world')" R --quiet
.
The specified string must be parsable by base::parse()
.
(Default: not specified)
(comma-separated values)
Controls whether an existing ‘./.RData’ file should be processed
or not.
If "remove"
, it will be skipped by automatically removing it.
If "rename"
, it will be renamed to ‘./.RData.YYYYMMDD_hhmmss’
where the timestamp is the last time the file was modified.
If "prompt"
, the user is prompted whether they want to load the file
or rename it. In non-interactive session, "prompt"
will fallback to
loading the content (default). To fallback to renaming the file, use
"prompt,rename"
.
If "warn"
, a warning will be produced, but content is still loaded.
Note that in contrast to R
and R CMD BATCH file.R
, Rscript
does
not load ‘.RData’ files unless command-line option --restore
is specified.
(Default: not specified)
(logical)
Controls the default value of argument check
of startup()
.
(Default: TRUE
)
(character vector or comma-separated character string)
Names of R options that should not be validated at the end of the
startup()
process.
(Default: "error"
)
(logical)
Controls the default value of argument debug
of startup()
.
(Default: FALSE
)
(character string or NULL)
Controls where startup()
debug messages are outputted.
If set, it specifies the file where debug messages are written to.
If file already exists, it is overwritten.
Unless an absolute filename is given, the location of the file is
relative to the working directory where R was started.
If the filename comprise the string {{pid}}
, it is replaced by
the R process' process identifier (PID) per Sys.getpid()
.
If NULL
or <message>
, then debug is outputted using the
message()
function.
(Default: not specified)
(character vector)
Overrides the command-line arguments that startup()
uses, which
can be useful to prototype and test alternative ways that R might
be launched.
(Default: base::commandArgs()
)
(POSIX timestamp; character string)
Overrides the current timestamp, which can be useful to prototype and
test functionalities that depend on the current time, e.g. inclusion
and exclusion of files based on when=<periodicity>
tags.
The specified string must be parsable by base::as.POSIXct()
.
(Default: not specified)
Information on the current R session
sysinfo()
sysinfo()
A named list.
startup::sysinfo()
startup::sysinfo()
Produce a warning
warn(..., call. = FALSE, immediate. = TRUE, domain = NULL)
warn(..., call. = FALSE, immediate. = TRUE, domain = NULL)
... , domain
|
The message and optionally the domain used for translation. The ... arguments are passed to base::sprintf to create the message string. |
call. |
If base::TRUE, the call is included in the warning message, otherwise not. |
immediate. |
If base::TRUE, the warning is outputted immediately, otherwise not. |