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 release_url argument. Currently the necessary C++ tool chain is assumed to be available, but in the future CmdStanR may help install the requirements. See the first few sections of the CmdStan installation guide for details on the required toolchain.

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().

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

Path to the directory in which to install CmdStan. The default is to install it in a directory called .cmdstanr within the user's home directory (i.e, file.path(Sys.getenv("HOME"), ".cmdstanr")).

cores

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

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 supress printing informational messages? The default is FALSE. If TRUE check_cmdstan_toolchain() only outputs errors.

overwrite

When an existing installation is found in dir, should CmdStan still be downloaded and reinstalled? The default is FALSE, in which case an informative error is thrown instead of overwriting the user's installation.

timeout

Timeout (in seconds) for the CmdStan build stage of the installation process.

version

Specifies the Cmdstan release version to be installed. By default set to NULL, which downloads the latest stable release from GitHub.

release_url

Specifies the URL to a specific Cmdstan release to be installed. By default set to NULL, which downloads the latest stable release from GitHub. If version and release_url are set, version is used.

cpp_options

A list specifying 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

Should install_cmdstan() check that the required toolchain is installed and properly configured. The default is TRUE.

append

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

# install_cmdstan(cores = 4) cpp_options <- list( "CXX" = "clang++", "CXXFLAGS+= -march-native", PRECOMPILED_HEADERS = TRUE ) # cmdstan_make_local(cpp_options = cpp_options) # rebuild_cmdstan() # check_cmdstan_toolchain(fix = FALSE, quiet = FALSE)