set_cmdstan_path.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/path.R
\name{set_cmdstan_path}
\alias{set_cmdstan_path}
\alias{cmdstan_path}
\alias{cmdstan_version}
\title{Get or set the file path to the CmdStan installation}
\usage{
set_cmdstan_path(path = NULL)

cmdstan_path()

cmdstan_version(error_on_NA = TRUE)
}
\arguments{
\item{path}{(string) The full file path to the CmdStan installation. If
\code{NULL} (the default) then the path is set using the \code{"CMDSTAN"}
environment variable when available, otherwise the default path used by
\code{\link[=install_cmdstan]{install_cmdstan()}} if it exists.}

\item{error_on_NA}{(logical) Should an error be thrown if CmdStan is not
found. The default is \code{TRUE}. If \code{FALSE}, \code{cmdstan_version()} returns
\code{NULL}.}
}
\value{
\code{set_cmdstan_path()} invisibly returns the supplied or automatically resolved
path. If \code{path = NULL} and no installation is found, it invisibly returns
\code{NULL}.

\code{cmdstan_path()} returns the current CmdStan path as a string or it errors if
no path has been set.

\code{cmdstan_version()} returns the CmdStan version as a string. If CmdStan is not
found, it errors when \code{error_on_NA = TRUE} and returns \code{NULL} when
\code{error_on_NA = FALSE}.
}
\description{
Use the \code{set_cmdstan_path()} function to tell CmdStanR where the
CmdStan installation is located. Once the path has been set,
\code{cmdstan_path()} will return the full path to the CmdStan installation and
\code{cmdstan_version()} will return the CmdStan version number. See \strong{Details}
for how to avoid manually setting the path in each \R session.
}
\details{
Before the package can be used it needs to know where the CmdStan
installation is located. When the package is loaded it tries to help automate
this to avoid having to manually set the path every session:
\itemize{
\item If the \link[=Sys.setenv]{environment variable} \code{"CMDSTAN"} points directly to
a valid CmdStan installation at load time, that path is used for the \R
session. If it instead points to an existing parent directory containing
versioned CmdStan installations, the installation with the largest version
number is used.
\item If no environment variable is found when loaded but any directory in the
form \code{".cmdstan/cmdstan-[version]"} (e.g., \code{".cmdstan/cmdstan-2.35.0"}),
exists in the user's home directory (\emph{not} the current working directory),
then the path to the CmdStan installation with the largest version number is
used for the \R session. On Windows the home directory is determined from
\code{USERPROFILE}, falling back to \code{HOMEDRIVE} and \code{HOMEPATH}. On other platforms
it is determined from \code{HOME}. This is the same default directory that
\code{\link[=install_cmdstan]{install_cmdstan()}} uses.
}

It is always possible to change the path after loading the package using
\code{set_cmdstan_path(path)}.
}
\seealso{
\code{\link[=install_cmdstan]{install_cmdstan()}}, \code{\link[=cmdstan_default_install_path]{cmdstan_default_install_path()}}, and
\code{\link[=cmdstan_default_path]{cmdstan_default_path()}}
}