\section{Introduction}\label{build_build_buildintro}
This document discusses how to build mlpack from source. These build directions will work for any Linux-\/like shell environment (for example Ubuntu, mac\+OS, Free\+B\+SD etc). However, mlpack is in the repositories of many Linux distributions and so it may be easier to use the package manager for your system. For example, on Ubuntu, you can install mlpack with the following command\+:


\begin{DoxyCode}
$ sudo apt-\textcolor{keyword}{get} install libmlpack-dev
\end{DoxyCode}


\begin{DoxyNote}{Note}
Older Ubuntu versions may not have the most recent version of mlpack available---for instance, at the time of this writing, Ubuntu 16.\+04 only has mlpack 2.\+0.\+1 available. Options include upgrading Ubuntu to a newer release, finding a P\+PA or other non-\/official sources, or installing with a manual build (below).
\end{DoxyNote}
If mlpack is not available in your system\textquotesingle{}s package manager, then you can follow this document for how to compile and install mlpack from source.

mlpack uses C\+Make as a build system and allows several flexible build configuration options. One can consult any of numerous C\+Make tutorials for further documentation, but this tutorial should be enough to get mlpack built and installed on most Linux and U\+N\+I\+X-\/like systems (including OS X). If you want to build mlpack on Windows, see \doxyref{Building mlpack From Source on Windows}{p.}{build_windows} (alternatively, you can read {\tt Keon\textquotesingle{}s excellent tutorial} which is based on older versions).

You can download the latest mlpack release from here\+: {\tt mlpack-\/3.\+3.\+0}\section{Simple Linux build instructions}\label{build_build_simple}
Assuming all dependencies are installed in the system, you can run the commands below directly to build and install mlpack.


\begin{DoxyCode}
$ wget https:\textcolor{comment}{//www.mlpack.org/files/mlpack-3.3.0.tar.gz}
$ tar -xvzpf mlpack-3.3.0.tar.gz
$ mkdir mlpack-3.3.0/build && cd mlpack-3.3.0/build
$ cmake ../
$ make -j4  # The -j is the number of cores you want to use \textcolor{keywordflow}{for} a build.
$ sudo make install
\end{DoxyCode}


If the {\ttfamily cmake} {\ttfamily }.. command fails, you are probably missing a dependency, so check the output and install any necessary libraries. (See \doxyref{Dependencies of mlpack}{p.}{build_build_dep}.)

On many Linux systems, mlpack will install by default to {\ttfamily /usr/local/lib} and you may need to set the {\ttfamily L\+D\+\_\+\+L\+I\+B\+R\+A\+R\+Y\+\_\+\+P\+A\+TH} environment variable\+:


\begin{DoxyCode}
export LD\_LIBRARY\_PATH=/usr/local/lib
\end{DoxyCode}


The instructions above are the simplest way to get, build, and install mlpack. The sections below discuss each of those steps in further detail and show how to configure mlpack.\section{Creating Build Directory}\label{build_build_builddir}
First we should unpack the mlpack source and create a build directory.


\begin{DoxyCode}
$ tar -xvzpf mlpack-3.3.0.tar.gz
$ cd mlpack-3.3.0
$ mkdir build
\end{DoxyCode}


The directory can have any name, not just \textquotesingle{}build\textquotesingle{}, but \textquotesingle{}build\textquotesingle{} is sufficient.\section{Dependencies of mlpack}\label{build_build_dep}
mlpack depends on the following libraries, which need to be installed on the system and have headers present\+:


\begin{DoxyItemize}
\item Armadillo $>$= 8.\+400.\+0 (with L\+A\+P\+A\+CK support)
\item Boost (math\+\_\+c99, program\+\_\+options, serialization, unit\+\_\+test\+\_\+framework, heap, spirit) $>$= 1.\+58
\item ensmallen $>$= 2.\+10.\+0 (will be downloaded if not found)
\end{DoxyItemize}

In addition, mlpack has the following optional dependencies\+:


\begin{DoxyItemize}
\item S\+TB\+: this will allow loading of images; the library is downloaded if not found and the C\+Make variable D\+O\+W\+N\+L\+O\+A\+D\+\_\+\+S\+T\+B\+\_\+\+I\+M\+A\+GE is set to ON (the default)
\end{DoxyItemize}

For Python bindings, the following packages are required\+:


\begin{DoxyItemize}
\item setuptools
\item cython $>$= 0.\+24
\item numpy
\item pandas $>$= 0.\+15.\+0
\item pytest-\/runner
\end{DoxyItemize}

In Ubuntu ($>$= 18.\+04) and Debian ($>$= 10) all of these dependencies can be installed through apt\+:


\begin{DoxyCode}
\textcolor{preprocessor}{# apt-get install libboost-math-dev libboost-program-options-dev}
  libboost-test-dev libboost-serialization-dev libarmadillo-dev binutils-dev
  python-pandas python-numpy cython python-setuptools
\end{DoxyCode}


If you are using Ubuntu 19.\+10 or newer, you can also install {\ttfamily libensmallen-\/dev} and {\ttfamily libstb-\/dev}, so that C\+Make does not need to automatically download those packages\+:


\begin{DoxyCode}
\textcolor{preprocessor}{# apt-get install libensmallen-dev libstb-dev}
\end{DoxyCode}


\begin{DoxyNote}{Note}
For older versions of Ubuntu and Debian, Armadillo needs to be built from source as apt installs an older version. So you need to omit {\ttfamily libarmadillo-\/dev} from the code snippet above and instead use {\tt this link} to download the required file. Extract this file and follow the R\+E\+A\+D\+ME in the uncompressed folder to build and install Armadillo.
\end{DoxyNote}
On Fedora, Red Hat, or Cent\+OS, these same dependencies can be obtained via dnf\+:


\begin{DoxyCode}
\textcolor{preprocessor}{# dnf install boost-devel boost-test boost-program-options boost-math}
  armadillo-devel binutils-devel python2-Cython python2-setuptools
  python2-numpy python2-pandas ensmallen-devel stbi-devel
\end{DoxyCode}


(It\textquotesingle{}s also possible to use python3 packages from the package manager---mlpack will work with either. Also, the ensmallen-\/devel package is only available in Fedora 29 or R\+H\+E\+L7 or newer.)\section{Configuring C\+Make}\label{build_build_config}
Running C\+Make is the equivalent to running {\ttfamily ./configure} with autotools. If you run C\+Make with no options, it will configure the project to build without debugging or profiling information (for speed).


\begin{DoxyCode}
$ cd build
$ cmake ../
\end{DoxyCode}


You can manually specify options to compile with debugging information and profiling information (useful if you are developing mlpack)\+:


\begin{DoxyCode}
$ cd build
$ cmake -D DEBUG=ON -D PROFILE=ON ../
\end{DoxyCode}


The full list of options mlpack allows\+:


\begin{DoxyItemize}
\item D\+E\+B\+UG=(O\+N/\+O\+FF)\+: compile with debugging symbols (default O\+FF)
\item P\+R\+O\+F\+I\+LE=(O\+N/\+O\+FF)\+: compile with profiling symbols (default O\+FF)
\item A\+R\+M\+A\+\_\+\+E\+X\+T\+R\+A\+\_\+\+D\+E\+B\+UG=(O\+N/\+O\+FF)\+: compile with extra Armadillo debugging symbols (default O\+FF)
\item B\+U\+I\+L\+D\+\_\+\+T\+E\+S\+TS=(O\+N/\+O\+FF)\+: compile the {\ttfamily mlpack\+\_\+test} program (default ON)
\item B\+U\+I\+L\+D\+\_\+\+C\+L\+I\+\_\+\+E\+X\+E\+C\+U\+T\+A\+B\+L\+ES=(O\+N/\+O\+FF)\+: compile the mlpack command-\/line executables (i.\+e. {\ttfamily mlpack\+\_\+knn}, {\ttfamily mlpack\+\_\+kfn}, {\ttfamily mlpack\+\_\+logistic\+\_\+regression}, etc.) (default ON)
\item B\+U\+I\+L\+D\+\_\+\+P\+Y\+T\+H\+O\+N\+\_\+\+B\+I\+N\+D\+I\+N\+GS=(O\+N/\+O\+FF)\+: compile the bindings for Python, if the necessary Python libraries are available (default ON except on Windows)
\item B\+U\+I\+L\+D\+\_\+\+J\+U\+L\+I\+A\+\_\+\+B\+I\+N\+D\+I\+N\+GS=(O\+N/\+O\+FF)\+: compile Julia bindings, if Julia is found (default ON)
\item B\+U\+I\+L\+D\+\_\+\+S\+H\+A\+R\+E\+D\+\_\+\+L\+I\+BS=(O\+N/\+O\+FF)\+: compile shared libraries as opposed to static libraries (default ON)
\item T\+E\+S\+T\+\_\+\+V\+E\+R\+B\+O\+SE=(O\+N/\+O\+FF)\+: run test cases in {\ttfamily mlpack\+\_\+test} with verbose output (default O\+FF)
\item D\+I\+S\+A\+B\+L\+E\+\_\+\+D\+O\+W\+N\+L\+O\+A\+DS=(O\+N/\+O\+FF)\+: Disable downloads of dependencies during build (default O\+FF)
\item D\+O\+W\+N\+L\+O\+A\+D\+\_\+\+E\+N\+S\+M\+A\+L\+L\+EN=(O\+N/\+O\+FF)\+: If ensmallen is not found, download it (default ON)
\item D\+O\+W\+N\+L\+O\+A\+D\+\_\+\+S\+T\+B\+\_\+\+I\+M\+A\+GE=(O\+N/\+O\+FF)\+: If S\+TB is not found, download it (default ON)
\item B\+U\+I\+L\+D\+\_\+\+W\+I\+T\+H\+\_\+\+C\+O\+V\+E\+R\+A\+GE=(O\+N/\+O\+FF)\+: Build with support for code coverage tools (gcc only) (default O\+FF)
\item P\+Y\+T\+H\+O\+N\+\_\+\+E\+X\+E\+C\+U\+T\+A\+B\+LE=(/path/to/python\+\_\+version)\+: Path to specific Python executable
\item J\+U\+L\+I\+A\+\_\+\+E\+X\+E\+C\+U\+T\+A\+B\+LE=(/path/to/julia)\+: Path to specific Julia executable
\item B\+U\+I\+L\+D\+\_\+\+M\+A\+R\+K\+D\+O\+W\+N\+\_\+\+B\+I\+N\+D\+I\+N\+GS=(O\+N/\+O\+FF)\+: Build Markdown bindings for website documentation (default O\+FF)
\item M\+A\+T\+H\+J\+AX=(O\+N/\+O\+FF)\+: use Math\+Jax for generated Doxygen documentation (default O\+FF)
\item F\+O\+R\+C\+E\+\_\+\+C\+X\+X11=(O\+N/\+O\+FF)\+: assume that the compiler supports C++11 instead of checking; be sure to specify any necessary flag to enable C++11 as part of C\+X\+X\+F\+L\+A\+GS (default O\+FF)
\item U\+S\+E\+\_\+\+O\+P\+E\+N\+MP=(O\+N/\+O\+FF)\+: if ON, then use Open\+MP if the compiler supports it; if O\+FF, Open\+MP support is manually disabled (default ON)
\end{DoxyItemize}

Each option can be specified to C\+Make with the \textquotesingle{}-\/D\textquotesingle{} flag. Other tools can also be used to configure C\+Make, but those are not documented here.

In addition, the following directories may be specified, to find include files and libraries. These also use the \textquotesingle{}-\/D\textquotesingle{} flag.


\begin{DoxyItemize}
\item A\+R\+M\+A\+D\+I\+L\+L\+O\+\_\+\+I\+N\+C\+L\+U\+D\+E\+\_\+\+D\+IR=(/path/to/armadillo/include/)\+: path to Armadillo headers
\item A\+R\+M\+A\+D\+I\+L\+L\+O\+\_\+\+L\+I\+B\+R\+A\+RY=(/path/to/armadillo/libarmadillo.so)\+: location of Armadillo library
\item B\+O\+O\+S\+T\+\_\+\+R\+O\+OT=(/path/to/boost/)\+: path to root of boost installation
\item E\+N\+S\+M\+A\+L\+L\+E\+N\+\_\+\+I\+N\+C\+L\+U\+D\+E\+\_\+\+D\+IR=(/path/to/ensmallen/include)\+: path to include directory for ensmallen
\item S\+T\+B\+\_\+\+I\+M\+A\+G\+E\+\_\+\+I\+N\+C\+L\+U\+D\+E\+\_\+\+D\+IR=(/path/to/stb/include)\+: path to include directory for S\+TB image library
\item M\+A\+T\+H\+J\+A\+X\+\_\+\+R\+O\+OT=(/path/to/mathjax)\+: path to root of Math\+Jax installation
\end{DoxyItemize}\section{Building mlpack}\label{build_build_build}
Once C\+Make is configured, building the library is as simple as typing \textquotesingle{}make\textquotesingle{}. This will build all library components as well as \textquotesingle{}mlpack\+\_\+test\textquotesingle{}.


\begin{DoxyCode}
$ make
Scanning dependencies of target mlpack
[  1%] Building CXX \textcolor{keywordtype}{object}
src/mlpack/CMakeFiles/mlpack.dir/core/optimizers/aug\_lagrangian/aug\_lagrangian\_test\_functions.cpp.o
<...>
\end{DoxyCode}


It\textquotesingle{}s often useful to specify {\ttfamily -\/jN} to the {\ttfamily make} command, which will build on {\ttfamily N} processor cores. That can accelerate the build significantly.

You can specify individual components which you want to build, if you do not want to build everything in the library\+:


\begin{DoxyCode}
$ make mlpack\_pca mlpack\_knn mlpack\_kfn
\end{DoxyCode}


One particular component of interest is mlpack\+\_\+test, which runs the mlpack test suite. You can build this component with


\begin{DoxyCode}
$ make mlpack\_test
\end{DoxyCode}


and then run all of the tests, or an individual test suite\+:


\begin{DoxyCode}
$ bin/mlpack\_test
$ bin/mlpack\_test -t KNNTest
\end{DoxyCode}


If the build fails and you cannot figure out why, register an account on Github and submit an issue and the mlpack developers will quickly help you figure it out\+:

{\tt https\+://mlpack.\+org/}

{\tt https\+://github.\+com/mlpack/mlpack}

Alternately, mlpack help can be found in I\+RC at \#mlpack on chat.\+freenode.\+net.\section{Installing mlpack}\label{build_install}
If you wish to install mlpack to the system, make sure you have root privileges (or write permissions to those two directories), and simply type


\begin{DoxyCode}
\textcolor{preprocessor}{# make install}
\end{DoxyCode}


You can now run the executables by name; you can link against mlpack with {\ttfamily -\/lmlpack}, and the mlpack headers are found in {\ttfamily /usr/include} or {\ttfamily /usr/local/include} (depending on the system and C\+Make configuration). If Python bindings were installed, they should be available when you start Python.\section{Using mlpack without installing}\label{build_build_run}
If you would prefer to use mlpack after building but without installing it to the system, this is possible. All of the command-\/line programs in the {\ttfamily build/bin/} directory will run directly with no modification.

For running the Python bindings from the build directory, the situation is a little bit different. You will need to set the following environment variables\+:


\begin{DoxyCode}
export LD\_LIBRARY\_PATH=/path/to/mlpack/build/lib/:$\{LD\_LIBRARY\_PATH\}
export PYTHONPATH=/path/to/mlpack/build/src/mlpack/bindings/python/:$\{PYTHONPATH\}
\end{DoxyCode}


(Be sure to substitute the correct path to your build directory for {\ttfamily /path/to/mlpack/build/}.)

Once those environment variables are set, you should be able to start a Python interpreter and {\ttfamily import mlpack}, then use the Python bindings.