Install CmdStan or clean and rebuild an existing installation

The install_cmdstan() function attempts to download and install the latest release of CmdStan. Installing a previous release or a new release candidate is also possible by specifying the version or release_url argument. See the first few sections of the CmdStan installation guide for details on the C++ toolchain required for installing CmdStan.

The rebuild_cmdstan() function cleans and rebuilds the CmdStan installation. Use this function in case of any issues when compiling models.

The cmdstan_make_local() function is used to read/write makefile flags and variables from/to the make/local file of a CmdStan installation. Writing to the make/local file can be used to permanently add makefile flags/variables to an installation. For example adding specific compiler switches, changing the C++ compiler, etc. A change to the make/local file should typically be followed by calling rebuild_cmdstan().

The check_cmdstan_toolchain() function attempts to check for the required C++ toolchain. It is called internally by install_cmdstan() but can also be called directly by the user.

install_cmdstan(
  dir = NULL,
  cores = getOption("mc.cores", 2),
  quiet = FALSE,
  overwrite = FALSE,
  timeout = 1200,
  version = NULL,
  release_url = NULL,
  cpp_options = list(),
  check_toolchain = TRUE
)

rebuild_cmdstan(
  dir = cmdstan_path(),
  cores = getOption("mc.cores", 2),
  quiet = FALSE,
  timeout = 600
)

cmdstan_make_local(dir = cmdstan_path(), cpp_options = NULL, append = TRUE)

check_cmdstan_toolchain(fix = FALSE, quiet = FALSE)

Arguments

dir	(string) The path to the directory in which to install CmdStan. The default is to install it in a directory called `.cmdstan` within the user's home directory (i.e, `file.path(Sys.getenv("HOME"), ".cmdstan")`).
cores	(integer) The number of CPU cores to use to parallelize building CmdStan and speed up installation. If `cores` is not specified then the default is to look for the option `"mc.cores"`, which can be set for an entire R session by `options(mc.cores=value)`. If the `"mc.cores"` option has not been set then the default is `2`.
quiet	(logical) For `install_cmdstan()`, should the verbose output from the system processes be suppressed when building the CmdStan binaries? The default is `FALSE`. For `check_cmdstan_toolchain()`, should the function suppress printing informational messages? The default is `FALSE`. If `TRUE` only errors will be printed.
overwrite	(logical) Should CmdStan still be downloaded and installed even if an installation of the same version is found in `dir`? The default is `FALSE`, in which case an informative error is thrown instead of overwriting the user's installation.
timeout	(positive real) Timeout (in seconds) for the build stage of the installation.
version	(string) The CmdStan release version to install. The default is `NULL`, which downloads the latest stable release from https://github.com/stan-dev/cmdstan/releases.
release_url	(string) The URL for the specific CmdStan release or release candidate to install. See https://github.com/stan-dev/cmdstan/releases. The URL should point to the tarball (`.tar.gz.` file) itself, e.g., `release_url="https://github.com/stan-dev/cmdstan/releases/download/v2.25.0/cmdstan-2.25.0.tar.gz"`. If both `version` and `release_url` are specified then `version` will be used.
cpp_options	(list) Any makefile flags/variables to be written to the `make/local` file. For example, `list("CXX" = "clang++")` will force the use of clang for compilation.
check_toolchain	(logical) Should `install_cmdstan()` attempt to check that the required toolchain is installed and properly configured. The default is `TRUE`.
append	(logical) For `cmdstan_make_local()`, should the listed makefile flags be appended to the end of the existing `make/local` file? The default is `TRUE`. If `FALSE` the file is overwritten.
fix	For `check_cmdstan_toolchain()`, should CmdStanR attempt to fix any detected toolchain problems? Currently this option is only available on Windows. The default is `FALSE`, in which case problems are only reported along with suggested fixes.

Value

For cmdstan_make_local(), if cpp_options=NULL then the existing contents of make/local are returned without writing anything, otherwise the updated contents are returned.

Examples

# \dontrun{
check_cmdstan_toolchain()
#> The C++ toolchain required for CmdStan is setup properly!

# install_cmdstan(cores = 4)

cpp_options <- list(
  "CXX" = "clang++",
  "CXXFLAGS+= -march=native",
  PRECOMPILED_HEADERS = TRUE
)
# cmdstan_make_local(cpp_options = cpp_options)
# rebuild_cmdstan()
# }