\chapter{Installing}

Mongrel2 is designed to build on most modern Unix systems, specifically Linux
and Mac~OSX\@.  It is written in C (\emph{not Ruby}) and uses fairly vanilla
C and standard libraries, except for one piece that implements the internal
coroutines.  Other than this, you should be able to compile and install Mongrel2
with nothing more than \shell{make all install} after you've installed
all the dependencies.

Now, if when I said dependencies you started to groan at having to install
software to use my software. Well, my friend, welcome to the future.  You
said you don't want people reinventing the wheel, right?  Great. That means
you need to install software for my software to work.  It's either that or
wait 10 years for me to build everything from scratch like some arrogant
jackass.

We good now?  Great, let's get started.

\section{Install Dependencies}

To get everything working you will need the following dependencies:

\begin{itemize}
\item GNU make (gmake).
\item \href{http://zeromq.org}{ZeroMQ 2.1.4} for the messaging.
\item \href{http://www.sqlite.org/}{SQLite3}.
\end{itemize}

If you install these things in this order, then everything should be good.

Since every system is different, it is difficult to tell you exactly how to
install required packages for your OS, but here's how I did it on my computer:

\begin{code}{Installing Dependencies on ArchLinux}
<< d['inputs/install_dependencies.sh|pyg|l'] >>
\end{code}

If you run into parts that your OS is missing, which is likely on
Debian and SuSE systems, then you'll have to go and figure out
how to install it.

Some distributions (like Ubuntu) split ``dev'' and ``runtime'' packages.
In order to build mongrel2 on these distros, you must install both.
The package libsqlite3-dev contains sqlite3.h, which Mongrel2 needs during
compilation, the package sqlite3 is needed for the unit tests.

Other pieces known to be missing on ubuntu-like systems:

\begin{itemize}
\item uuid-runtime: Needed by m2sh uuid command
\item You may need to run: \shell{sudo ldconfig -v}
\end{itemize}

For the lazy, the command is: \shell{sudo apt-get install uuid-runtime sqlite3 libsqlite3-dev}


\section{Getting Mongrel2}

If everything went well, you should be able to grab the Mongrel2 source
and try building it.  There's two ways you can get the source code to
Mongrel2:

\begin{enumerate}
\item Install \href{http://git-scm.org}{Git} and check out the source.
\item Grab the source .zip or tar.bz2 release and install it from there.
\end{enumerate}


\subsection{Using the .tar.bz2 File}

The easiest way to build Mongrel2 is to use the .tar.bz2 file from 
\href{http://mongrel2.org/home#download}{the main page downloads} section.
Simply download it and you're done.


\subsection{Using git}

If you like living on the edge then here's how to follow the development source
tree while we work on it:

First, get git running on your system, through your package manager or fetch
the proper sources or binaries from the \href{http://git-scm.com/download}{Git Download page}.

Once you have git you can then get the Mongrel2 source and open it up:

\begin{code}{Cloning the Mongrel2 Source}
<< d['inputs/cloning_mongrel2_source.sh|pyg|l'] >>
\end{code}

Make sure you do this in order (just like with every set of instructions you follow)
or else you'll get errors.

In order to stay up-to-date with all the changes, remember to periodically
update your checkout (make sure you're in the latest version before reporting
a bug!). It's as simple as \shell{git pull}. And remember to rebuild and install
afterwards!

\section{Building And Installing}

Once you have the source ready to go you can build it and then install it with
one command:  \shell{make all install}

There is no \shell{./configure} for Mongrel2 since we avoid too many OS specific
differences or shield those away with good feature checks in the code.

If you want to install to a different location than the default  \file{/usr/local},
use \shell{PREFIX=/path/to/somewhere make all install} instead.

The end result of this should be:

\begin{enumerate}
\item Mongrel2 builds and compiles without errors.
\item All the unit tests run.\footnote{Please tell us about failures.}
\item The \shell{m2sh} binary gets installed.
\item The \shell{mongrel2} binary gets installed.
\end{enumerate}

If any of these stages fail, then you can simply try to fix them and then
run:  \shell{make clean all \&\& sudo make install}, which will do everything all over again.

\subsection{Other platforms than Linux}

If you aren't running Linux, chances are good this standard procedure will not work for you.

The \file{Makefile} lists several targets for various platforms. As of writing this, there are:

\begin{itemize}
\item freebsd
\item netbsd
\item openbsd
\item macports
\end{itemize}

So, for example, you would probably install zeromq and sqlite3 as ports and then compile it like so:

\begin{code}{Installing Mongrel2 on FreeBSD}
<< d['inputs/install_freebsd.sh|pyg|l'] >>
\end{code}

\section{Testing The Installation}

When you are done, you probably want to make sure that it installed correctly.
There's a test configuration file in \file{tests/config.sqlite} that you can
use to try it out:

\begin{code}{First Test Run}
<< d['inputs/first_mongrel2_run.sh|pyg|l'] >>
\end{code}

That's it!  Just hit CTRL-c for now and we'll get into playing with this
setup later.



\section{Up Next}

You now should have a working Mongrel2 system installed and the m2sh configuration
interface ready to go.  In the rest of this manual we'll be simply learning how
to do more with Mongrel2, like making our own configs, writing handlers, and other
fun stuff.

