%\VignetteIndexEntry{Installation for Developers}
\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage{hyperref}
\hypersetup{colorlinks=true}
\usepackage{menukeys} 
\usepackage{graphicx}
\usepackage{float}
\usepackage{listings,textcomp} % for R code blocks

\title{Installation Instructions Manual for \texttt{dynr} - Developer version}
\author{Michael D. Hunter, Sy-Miin Chow,  Lu Ou, Sukruth N. Reddy,\\ 
Meng Chen, Linying Ji, Jungmin Lee, Xiaoyue Xiong, \& Sharon Kim}
\date{\today}

\begin{document}
\SweaveOpts{concordance=TRUE}

\maketitle
The \texttt{dynr} software is a package for R written in R and C.  It has utilities which allow users to create C code for linear and nonlinear dynamic models, including regime-switching models, without ever having to actually write C code.  Various functions in R are called by the user to specify the model desired.  These functions in turn write code in C based on the user's input.  These functions are then compiled and shared with the rest of the \texttt{dynr} C code to estimate the model, obtaining free parameter estimates, standard errors, and latent variable estimates.

\section{\Large Instructions for Installing and Using \texttt{dynr} on a Windows Computer}
Because the \texttt{dynr} package compiles C code in response to user input, more setup is required for the \texttt{dynr} package than for many others. The general requirements are as follows:

\begin{enumerate}
\item R must be installed in a directory without spaces in the path.  See Section \ref{sec:R}.
\item Rtools must be installed so that C code can be compiled on Windows. See Section \ref{sec:Rtools}.
\item Additional GSL libraries must be installed so that the C code can use GSL for matrix multiplication routines. See Section \ref{sec:gsl}.
\item The environment variable for the system Path must be modified to include R and Rtools. See Section \ref{sec:rpath}.
\item An environment variable for GSL called LIB\_GSL must be created. See Section \ref{sec:libgsl}.
\end{enumerate}

Each of these steps is detailed below.  We acknowledge that this additional setup can be bothersome, but we believe the ease of use for the rest of the package and the wide variety of models it is possible to fit with it will compensate for this initial burden.  Hopefully you will agree!

\subsection{\Large Instructions for Installation of R}
\label{sec:R}
\begin{itemize}
    \item Make sure that R is installed and Check the directory in which R is installed.
    \item If not go to \href{https://www.r-project.org/}{https://www.r-project.org/}  and click on download R and select any mirror.
    \item The critical step is just to make sure that you install R to a directory where there are {\bf no spaces} in the words describing the directory.  By default, it will suggest to install R in {``C:\textbackslash Program Files''} on your computer. Instead change it to just {``C:\textbackslash''} {\em or any other directory where there are {\bf no spaces} in the words describing the directory}. For example as given in the default directory ``Program Files'' has a space in between the two words so avoid using such directories.
\end{itemize}


\subsection{\Large Instructions for Installation of R-tools }
\label{sec:Rtools}
\begin{enumerate}
\item If you already have R-tools on your machine, make sure the version of R-tools matches with your R version. R-tools versions newer than 3.0 should work fine with \texttt{dynr}.
\item Install R-tools through \url{https://cran.r-project.org/bin/windows/Rtools/}. Install the latest {\em release} version of Rtools, not the {\em devel} version. 
\item The following instructions are based on rtools42.
\item Click ``Rtools42 installer'', then click ``rtools42-5355-5357.exe`` in the new webpage. You may be asked if you want to save or run a file ``rtools42-5355-5357.exe``. Choose ``Save'' and save the file on the Desktop. Then double-click on the icon for the file to run it.
\item If you are asked what language to install, choose English.
\item The next page says ``Select Destination Location`` at the top. By default, it will suggest to install R in ``C:\textbackslash rtools42'' on your computer. You may also install R-tools in  {\em any other directory where there are {\bf no spaces} in the words describing the directory}. Click ``Next'' at the bottom of the R tools Setup wizard window.
\item The next page says ``Select additional tasks`` at the top. Check the box to edit the system PATH. Click ``Next'' again.
\item Add the directories for R and Rtools to your {\em system} PATH.  Examples are shown below.  Place these directories at or near the top of your list for the {\em system} PATH variable. The order of the directories should be the same as shown in the example below.\\
\texttt{C:\textbackslash rtools42\textbackslash usr\textbackslash bin\\
 C:\textbackslash R\textbackslash R-4.2.1\textbackslash bin\textbackslash x64;}\\ % TODO check if x64 is needed
You may want to first go to the directory where Rtools and R are installed and check that you know the correct pathway.  
\item The next page says ``Ready to install'' at the top. Click ``install''.
\item Rtools should now be installed. This will take about a minute. Click ``Finish''.
\end{enumerate}



\subsection{\Large Instructions for Installation of GSL}
\label{sec:gsl}
\begin{enumerate}
\item If you already have GSL libraries installed on your machine, you may skip this step and go to Section \ref{sec:libgsl}.  
\item To install GSL libraries, we advocate using Rtools.  The new way to get GSL is through Rtools.
\item  Go to the directory on your computer for Rtools (usually \texttt{C:/rtools42} or something similar).  There’s a file called \texttt{msys2.exe}.  Run it.  It should open a shell command prompt.  Type\\
\\
\texttt{pacman -Sy mingw-w64-x86\_64-gsl}\\
\\
in that command prompt.  This installs GSL.  Check by going to \texttt{C:/rtools42/mingw64/lib}, and find a file called \texttt{libgsl.a}.  If it’s there, then it installed GSL.
\item If it's not there, then \texttt{pacman} probably did not install GSL correctly.  Search online for ``msys2'' and ``GSL'' to find updated commands for installing GSL with msys2.
 \end{enumerate}


\subsection{\Large Setting up the GSL Environment Variable}
\label{sec:libgsl}
\begin{enumerate}
 \item Open - Control Panel\textbackslash System and Security\textbackslash System
 \item Click on Advanced system settings and then click on ``Environment Variables''
 \item Add a new {\em system} variable by clicking on New.  Note that this should be a {\em System} environment variable, not a {\em User} environment variable.
 \item Name the new variable as LIB\_GSL and set the variable value to the 
 directory one back from \texttt{libgsl.a}.  This file is usually in \texttt{C:/rtools42/mingw64/lib}, so you'll set \texttt{LIB\_GSL} to \texttt{C:/rtools42/mingw64}.
 \item Note that the direction of these slashes is important. This slash / will work but {\em not} this one \textbackslash.  The \texttt{LIB\_GSL} path should be \texttt{C:/rtools42/mingw64} and not \texttt{C:\textbackslash rtools42\textbackslash mingw64}.
\end{enumerate}


\subsection{\Large Setting up R and Rtools Environment Variable}
\label{sec:rpath}
\begin{enumerate}
 \item Check if R can be run through CMD as follows. Put a simple R script (e.g., save a simple R command: print (``hello'') to a .R document as ``Hello.R'') to a known directory. Open the command prompt window. If you can't find it just do a search from the Start Menu for ``cmd'' and open ``Command Prompt.exe''. Then change directory to the location containing ``Hello.R'' (e.g., cd C:\textbackslash myfiles). Run the script by typing ``Rscript Hello.R''. If the file runs correctly, it should print out ``hello'' in the command prompt console.
 \item Close your command prompt window.
 \item If the file did not run correctly, follow the next 4 steps.
 \item Open - Control Panel\textbackslash System and Security\textbackslash System
 \item Click on Advanced system settings
 \item Check to make sure that your path variable specified during Rtools installation is specified correctly. In Windows 10 do so by clicking on ``Environment Variables'' and then in the ``System variables'' panel click on ``Path'' and then ``Edit''. Check that the following paths have been specified at the front of your {\em system} path variable or just move them all to way up to the top in the following order.
\\
\texttt{C:\textbackslash rtools42\textbackslash usr\textbackslash bin\\
 C:\textbackslash R\textbackslash R-4.2.1\textbackslash bin\textbackslash x64\\
 C:\textbackslash cygwin\textbackslash bin (see section \ref{sec:cygwin})
 }
 \item The order of the directories on the PATH variable is important.  CMD looks for programs starting at the top of the directories in PATH.  Make sure you have Rtoos, then R, then cygwin.
 \item Repeat (1) and see if you can now run R from CMD. Make sure that you open a new CMD window after you have completed the steps above. Try typing in ``PATH'' in CMD to make sure that the newly added paths are indeed shown in the output.
\end{enumerate}



\subsection{\Large Instructions for Installation of Cygwin}
\label{sec:cygwin}
\begin{enumerate}
\item Install Cygwin through \url{https://cygwin.com/index.html}.
\item When prompted, select to install the following packages in cygwin: 
\begin{enumerate}
\item git (under Devel): "Distributed version control system"
\item gcc (under Devel): "gcc-core: GNU Compiler Collection (C, OpenMP)"
\item make (under Devel): "The GNU version of the 'make' utility"
\item perl: (under Perl): "Perl programming language interpreter"
\end{enumerate}
\item Make sure that \texttt{C:\textbackslash cygwin\textbackslash bin} is in the path variable, if not, add it
\end{enumerate}

\subsection{\Large Wrapping up the Installation Procedure for Windows}
\label{wrapup}
\begin{enumerate}
\item Open RGui, Rstudio or whatever editor you use to run R. Please type the following code to check whether the gsl commands can be found correctly:\\ \texttt{shell("echo \%LIB\_GSL\%")}\\ If this returns something like \texttt{C:/rtools42/mingw64}, then everything worked fine.
 \item If that command returns something like ``\%LIB\_GSL\%'', then something might be wrong with the GSL installation (Return to Section \ref{sec:gsl}) or GSL path (Return to Section \ref{sec:libgsl}).
 \item If the command worked fine, follow the steps in section \ref{sec:GitHub} to finish the installation process in R.
\end{enumerate}



\section{\Large Instructions for Installing and Using \texttt{dynr} On Mac}

\subsection{\Large Instructions for Installing Prerequisites on Mac}
\label{sec:macpre}
\begin{enumerate}
\item Open your terminal window and type in \texttt{xcode-select -{}-install} and follow the instructions for all the subsequent steps. Please pick the correct software version for your operating system.
\begin{itemize}
\item \textbf{NOTE:} If you have Big Sur as your Operating System, you do not need to install the command line tools. In fact, you need to remove it by navigating to /Library/Developer and remove Command Line Tools. 
\item Then, edit /Library/Frameworks/R.framework/Resources/etc/Makeconf and remove all compilers’ explicit link to a particular OS; e.g., change "CC=clang -mmacosx-version-min=10.16" to just "CC=clang." Please see the FAQ section on the \href{https://dynrr.github.io/FAQ.html}{dynr GitHub webpage} for further updates.
\end{itemize}
\item Install Macports by going to \url{https://www.macports.org/install.php}
\item Open the terminal window. In the terminal window install the gsl library by typing: ``sudo port install gsl''.
\item Follow the steps in section \ref{sec:maccheck} to verify that these steps worked properly.
\end{enumerate}

\subsection{\Large Checking the Installation for Mac}
\label{sec:maccheck}
\begin{enumerate}
\item Open RGui, Rstudio or whatever editor you use to run R. Please type the following code to check whether the gsl commands can be found correctly:\\ \texttt{system("gsl-config -{}-cflags", intern=TRUE)}\\ When the command can not be found, and you know where it is stored (e.g., "/opt/local/bin"), we could then set the PATH variable by typing: \\
\texttt{Sys.setenv(PATH=paste0(Sys.getenv("PATH"),":","/opt/local/bin"))}\\ and then check again.
\item If the above failed, then something went wrong with one or several of the steps in Section \ref{sec:macpre}. Please go back and try repeating or checking that section.
\item Follow the steps in section \ref{sec:GitHub} to finish the installation process in R.
\end{enumerate}

% \section{\Large Installing Rcpp, RcppGSL, and RcppArmadillo dependencies}
% \label{sec:arma}
% A few extra steps are needed to use utility functions in Rcpp, RcppGSL, and RcppArmadillo to facilitate programming. These steps include:
% \begin{enumerate}
% \item Paste in steps from Brekfis/Admin%/armadillo\_test\_on_Windows\_and_OSx\_v3.docx
% \end{enumerate}


\section{\Large Getting \texttt{dynr} from GitHub Repository}
\label{sec:GitHub}
\begin{enumerate}
\item Create a GitHub account if you don't already have one (\url{https://github.com/}). Email Michael D. Hunter (\href{mailto:mike.dynr@gmail.com}{mike.dynr at gmail.com}) for permission to dynr's GitHub repository.
\item Once permission is granted, open a Command Prompt window (it can be done by searching ``cmd" in the windows search box) on Windows, or a Terminal window on Macs, and change the directory to a desired location for the dynr package folder (e.g. by typing \texttt{cd <path to location>}).
\item Clone the repository from GitHub. It should involve typing something like \texttt{git clone <https://github.com/mhunter1/dynr.git>} in the window.
\item Install the dependencies of dynr yourself.
\item There is a bug in \texttt{roxygen2} such that the latest version will not build our documentation. It is a known issue that will be resolved soon. In the meantime, use an older version of the package. Install it with \texttt{devtools::install\_version(package $=$ 'roxygen2',version $=$ '5.0.1', repos $=$ c(CRAN $=$ ``https://cran.rstudio.com''))}
\item Install \texttt{dynr} by running \texttt{make clean install} in the Command Prompt/Terminal window.
\item To test if \texttt{dynr} is installed correctly, run one of the demo examples in R. For instance, type: \\
\texttt{demo(`LinearSDE',package=`\texttt{dynr}')}\\
\texttt{Press $<$Return$>$ to start the demo.}\\
Note that this specific demo requires the packages \textit{Matrix} and \textit{mvtnorm} so make sure that these have been installed.
\item If you're on Windows and everything worked fine until you tried to run the model, something probably went wrong with installing Rtools (Section \ref{sec:Rtools}) or installing GSL (Section \ref{sec:gsl}). Please refer to those sections for troubleshooting.
\end{enumerate}


\section{\Large Advanced Operations When Developing Dynr}
\label{sec:Advope}

\subsection{\Large Import Functions in \texttt{dynr}}
\label{sec:exportfuns}
\begin{enumerate}
  \item Make sure that you have a local \texttt{dynr} repository in your computer.
  \item Change the \texttt{NAMESPACE} file.
  \begin{itemize}
      \item Find the \texttt{NAMESPACE} file in the \texttt{dynr} directory. Open it by any code editor (e.g., TextEdit on Mac or Wordpad on Windows).
     \item Add one line to import the package with \texttt{importFrom} function or \texttt{import} function at the end of the file, so that you can use corresponding datasets and functions from that package when using \texttt{dynr} package. For example, add \texttt{import(Rcpp)} to use \texttt{Rcpp} package. 
     \item More details can be found in <Managing imports and exports> (\url{https://cran.r-project.org/web/packages/roxygen2/vignettes/namespace.html}) and more examples can be found in the \texttt{NAMESPACE} file.
     \item Save and quit the file.
    \end{itemize}
  \item Change the \texttt{description.in} file.
  \begin{itemize}
      \item Find the \texttt{description.in} file in the \texttt{dynr} directory. Open it by any code editor (e.g., TextEdit on Mac or Wordpad on Windows).
     \item Locate the line that begins with \texttt{Imports:}, and add the name of the package which you want to import at the end of the line.
      \item Save and quit the file.
    \end{itemize}
\end{enumerate}

\subsection{\Large Export Functions from Other R Packages}
\label{sec:exportfuns}
\begin{enumerate}
\item Make sure that you have a local \texttt{dynr} repository in your computer.
\item Find the \texttt{NAMESPACE} file in the \texttt{dynr} directory. Open it by any code editor (e.g., TextEdit on Mac or Wordpad on Windows).
\item Add one line to export the package with \texttt{export, exportS3Method, exportClass, exportMethod} or \texttt{exportPattern} function at the end of the file. More details can be found in <Managing imports and exports> (\url{https://cran.r-project.org/web/packages/roxygen2/vignettes/namespace.html}) and more examples can be found in the \texttt{NAMESPACE} file.
\item Save and quit the file.
\end{enumerate}

\end{document}