\documentclass[12pt]{article}
\usepackage{Sweave}

%\VignetteIndexEntry{Compiling pcaPP for Matlab}
%\VignetteDepends{pcaPP}
%\VignetteKeywords{Matlab}
%\VignettePackage{pcaPP}

<<results=tex,fig=FALSE,echo=FALSE>>=

source ("load.package.name.R")

library (package.name, character.only = TRUE)

vt <- eval (parse (text = paste (package.name, ":::", ".getVtext", sep = "")))

cat (sep = "",
#	"%\\VignetteIndexEntry{Compiling ", vt (1), " for Matlab}\n",	##	these lines cannot be created automatically - unfortunately..
#	"%\\VignetteDepends{", vt (1), "}\n",
#	"%\\VignetteKeywords{Matlab}\n",
#	"%\\VignettePackage{", vt (1), "}\n",
#	"\n",
	"\n",
	"\\newcommand{\\dapck}{", vt (1), "}\n",
	"\\newcommand{\\daver}{", vt (2), "}\n",
	"\n",
	"\n"
)
@

\newcommand{\sourcefile}{{\dapck}\_{\daver}.tar.gz}

\newcommand{\proglang}[1]{\textbf{#1}}
\newcommand{\code}[1]{\texttt{#1}}
\newcommand{\link}[1]{\texttt{#1}}
\newcommand{\path}[1]{{\it #1}}


\title{Compiling {\dapck} for Matlab}
\author{Heinrich Fritz}


\begin{document}
\maketitle

\section{Introduction}
The main functions of the 
\proglang{R}-package {\dapck} are implemented in an environ-mentindependent 
manner, which allows the user to use this package beyond the scope of \proglang{R}.
The package has also been prepared to be compiled and used with \proglang{Matlab}, which 
is summarized and demonstrated in this document.
The following items are required for using {\dapck} together with \proglang{Matlab}:

\begin{itemize}
\item The {\dapck} package sources \code{\sourcefile} \\(available at \link{http://CRAN.R-project.org/package=\dapck}).
\item \proglang{Matlab} (version $\geq$ 2010a).
\item A compatible \proglang{C++} compiler (for currently supported compilers see \link{http://www.mathworks.com/support/compilers/current\_release/}).
\end{itemize}
Section \ref{sec:instcomp} helps to set up a suitable compiler together with 
\proglang{Matlab}, whereas Section \ref{sec:comp} gives instructions on how to 
actually compile the package. 
Section \ref{sec:ex} demonstrates some examples on the usage of the package and 
Section \ref{sec:concl} concludes.

\section{Setting up the Compiler} \label{sec:instcomp}
Assuming that \proglang{Matlab} has already been set up properly on the target 
system, the first step is to set up a suitable \proglang{C++} compiler, such that \proglang{Matlab} 
recognizes it.
A list of compatible compilers can be obtained by typing
\begin{Scode}
>> mex -setup
   n
\end{Scode}
into the \proglang{Matlab} console.
Once a compiler from this list has been installed on the system, select it
(by using the previous command)
and make sure that \proglang{Matlab} locates it correctly.
Note that after installing a compiler \proglang{Matlab} might have to be 
restarted for correctly recognizing it.
Finally assure that the compiler has been set up properly by typing
\begin{Scode}
>> mex.getCompilerConfigurations ('C++')
\end{Scode}
\proglang{Matlab} should now correctly display the chosen compiler's details.
A more extensive introduction to the mex-interface and its configuration can be found at
\code{http://www.mathworks.de/support/tech-notes/1600/1605.html}.

\section{Compiling {\dapck}} \label{sec:comp}

Extract the downloaded package sources (\code{\sourcefile}) to a working directory,
(e.g. \path{C:/work}),
and set \proglang{Matlab}'s current directory to the \path{{\dapck}/matlab} subfolder:
\begin{Scode}
<<results=tex,fig=FALSE,echo=FALSE>>=
cat (sep = "",
	">> cd ('C:/work/", vt(1), "/matlab')")
@

\end{Scode}
Now the package is ready to be compiled by calling {\dapck}'s \code{setup} routine:
\begin{Scode}
>> setup
Changing the current directory to '../src' ... ok
<<results=tex,fig=FALSE,echo=FALSE>>=
cat (sep = "",
	"Compiling the ", vt(1), " package ... ok\n",
	"Copying the '", vt(1), ".mex*' file(s) to '../matlab' ... ok\n",
	"Changing the current directory back to '../matlab' ... ok\n\n",
	"  Successfully compiled the ", vt(1), " package for Matlab!")
@

\end{Scode}
Note that this \proglang{Matlab}-setup routine has been tested with Microsoft's Visual C++ 6.0 compiler.
Other compilers supported by \proglang{Matlab} are very likely to work as well, but have not been tested in this context yet.

\section{Using {\dapck}} \label{sec:ex}
Once the preceding code has been executed successfully, the {\dapck} package can 
be used almost the same way as in \proglang{R}.
The following functions are available in \proglang{Matlab}:
<<results=tex,fig=FALSE,echo=FALSE>>=
cat (paste ("\\code{", vt(3), "}", sep = "", collapse = ", "))
@

and work as described in the \proglang{R} man pages:

\begin{Scode}
<<results=tex,fig=FALSE,echo=FALSE>>=
	cat (vt (4))
@


\end{Scode}

\section{Conclusions} \label{sec:concl}
The configuration of a \proglang{C++} compiler in the context of \proglang{Matlab} has 
been discussed briefly, as well as how to compile the \proglang{R} package {\dapck} in 
this environment.
Further some examples on how to use the package in \proglang{Matlab} were given.
Due to the package's architecture the same \proglang{C++} sources can be used in 
both environments, which increases the availability of this software beyond the scope
of the \proglang{R} community.

\end{document}
