Skip to contents

Install CmdStan or clean and rebuild an existing installation

Source: R/install.R
install_cmdstan.Rd

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. If the CmdStan installation currently in use has a non-empty make/local file, the flags in it can be copied to the new installation before it is built, so that no rebuild is needed afterwards. In an interactive session install_cmdstan() shows the file and asks. See the copy_make_local argument to decide without being asked.

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.

CmdStan versions older than 2.37.0 are no longer supported. If you need to work with an older CmdStan version we recommend installing an older CmdStanR release from GitHub.

Usage

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

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. On Windows the home directory is determined from USERPROFILE, falling back to HOMEDRIVE and HOMEPATH. On other platforms it is determined from HOME.

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. The default is 1200 seconds for install_cmdstan() and 600 seconds for rebuild_cmdstan().

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.37.0/cmdstan-2.37.0.tar.gz". If both version and release_url are specified then version will be used.

release_file

(string) A file path to a CmdStan release tar.gz file downloaded from the releases page: https://github.com/stan-dev/cmdstan/releases. For example: release_file="./cmdstan-2.37.0.tar.gz". If release_file is specified then both release_url and version will be ignored.

cpp_options

(list) Any makefile flags/variables to be written to the make/local file. For install_cmdstan() they are written before CmdStan is built, so no rebuild is needed. A named entry is written as an assignment, so list(CXX = "clang++") builds with clang, TRUE turns a switch on (list(stan_threads = TRUE) gives STAN_THREADS=true) and FALSE turns it off (STAN_THREADS=). An unnamed string is written as is, which is how a line like "CXXFLAGS += -march=native" goes in.

check_toolchain

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

wsl

(logical) Should CmdStan be installed and run through the Windows Subsystem for Linux (WSL). The default is FALSE.

copy_make_local

(logical) Should the make/local file of the CmdStan installation currently in use be copied to the new installation? The copy happens before CmdStan is built, so the flags are already in effect for that build. The default is NULL, which shows the previous make/local and asks in an interactive session, and copies nothing otherwise. The question comes before the download, so that the rest of the installation runs unattended. Use TRUE or FALSE to decide without being asked. Flags given in cpp_options are written after the copied ones and therefore take precedence.

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. When appending, a flag that is already in make/local is not written again.

fix

Deprecated and will be removed in a future release. This argument is ignored and retained only for compatibility.

Value

If a build fails or times out, install_cmdstan() issues a warning and invisibly returns the process result.

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.

See also

set_cmdstan_path(), cmdstan_default_install_path(), and cmdstan_default_path()

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()
# }