\chapter{Building and Installing MX}

\section{Prerequisites}

The first step in building MX is to set up the environment in which
to compile and install the source code.  For Microsoft Windows, this is
a somewhat complicated and long process.  For most of the
other MX build targets, the process is much, much simpler.

\subsection{Linux}
Due to the available package managers and distribution repositories, Linux
is one of the easier systems on which to set up an MX build environment.
For many Linux distributions, all of the prerequisite packages
will already be available from your package repositories.

\ \newline
The most commonly used Linux distributions for MX are:
\begin{itemize}
  \item \textbf{Debian} - Debian GNU/Linux is the primary development platform
	for MX on Linux.\\
  \item \textbf{RHEL, CentOS, Scientific Linux} -
	There are a number of sites that run MX on this family of 
	distributions.  If you want to use any of the MX GUI programs,
	then you should plan on adding the
	``Extra Packages for Enterprise Linux (EPEL)'' repository to
	your list of repositories.  RHEL, for example, definitely
	does not contain all of the packages needed to build the
	wxPython GUIs in the base system.\\
\end{itemize}

\subsubsection{Linux Installation}

We will use the Debian 7.0 (amd64) distribution as our example
in the following description.  For the most parts, the details for
other distributions should be similar.

MX is most commonly used on the ``amd64'', ``x86'', and 
``powerpc'' Debian ports.  The ``armel'' and ``armhf'' ports are
also likely to be used in the future.  A small amount of testing
has also been done for various versions of the ``alpha'', ``ia64'',
``m68k'', ``mips'', ``mipsel'', ``s390'', ``sh'', and ``sparc'' ports,
but this has typically been to just verify that the code compiles,
with brief testing of the binaries.

The first step is to install Debian (or another Linux distribution)
on your computer.  There are many online references and books that
describe this process, so I will not go into it here.  Early on in
the installation process, Debian will display a ``Software selection''
screen.  At this screen, I will generally select at least the ``SSH server''
task, since that makes remote administration much easier.  For servers,
I often install little more than this, while for clients you can install
whatever GUI environments that they are most comfortable with.

However, in the following description, I assume that you only installed
the base Debian distribution, with only the OpenSSH programs added.
This makes it easier to enumerate the list of packages that are actually
required for various MX components.

\subsubsection{Packages Needed to Compile MX (C/C++ support)}

The source code to the core of MX is generally distributed either as
a compressed tar file from
the MX web site \textit{http://mx.iit.edu} 
with a name like \textit{mx-2.0.0.tar.gz} 
or by downloading the source code using Subversion from the MX Subversion
repository like this

\textit{svn checkout http://svn.csrri.iit.edu/mx/trunk mx}.
\newline
The source code in the \textit{mx/modules} subdirectory is for 
optionally compiling
dynamically loadable modules that make use of external software that
may not always be present such as EPICS.
However, the rest of the MX core is
intended to be built on all MX installations.  Compiling modules is
described later in this manual.

In order to build the MX core, you need at least a compiler and GNU make.
On Wheezy (Debian 7), the following set of packages should be sufficient
for that
\begin{itemize}
  \item \textbf{gcc} - The GNU C compiler.  Selecting this package should
	automatically result in the installation of a number of other
	needed packages like \textbf{binutils}, \textbf{cpp},
	\textbf{libc6-dev}, and so forth, but the dependency handling of
	the Debian \textit{apt-get} or \textit{aptitude} commands should
	take care of automatically selecting all of the
	other needed packages for you.
  \item \textbf{make} - The GNU make program.
\end{itemize}

Other things that are convenient to have, but not absolutely required, include
\begin{itemize}
  \item \textbf{gdb} - The GNU debugger.
  \item \textbf{subversion} - Used to download MX source code from
	the Subversion repositories.
\end{itemize}

Installation of the above packages and their dependencies, should be enough
to build and install a completely functional version of the MX core.

\subsubsection{Packages Needed to Compile Mp (Python support)}

Mp provides the Python API for MX.  At present, Python 3.x is not supported
and will not be until after MX 2.0.0 is released.

The following packages are required to build Mp.
\begin{itemize}
  \item \textbf{python} - Python 2.7 is best for now.
  \item \textbf{python-dev} - Provides the C API for Python extension modules
	such as Mp.
  \item \textbf{python-numpy} - It is possible to build Mp without Numpy
	support.  However, array and image operations will run much, much
	slower, so you are strongly encouraged to install \textbf{python-numpy}.
\end{itemize}

\subsubsection{Packages Needed to Support WxPython-based GUIs}

The following package is needed for WxPython support
\begin{itemize}
  \item \textbf{python-wxgtk2.8} - Installing this package should pull in 
	all of the other packages needed to support basic Mp GUI functionality.
  \item \textbf{python-imaging} - Python Imaging Library (PIL) is required
	by Mp GUIs that display
	two dimensional area detector images such as \textit{mpad}.
\end{itemize}

Other useful (but not required) packages include
\begin{itemize}
  \item \textbf{python-matplotlib} - An excellent two-dimensional graphing
	package.
\end{itemize}

%---------------------------------------------------------------------

\subsection{Mac OS X}

In many ways, Mac OS X is much easier to set up for MX than Linux.  If first
you install Xcode, which is Apple's software development toolkit, almost
everything that you need to develop MX software will already be installed.
You will already have a C/C++/Objective C compiler, Python, and WxPython.
The only item missing is the Python Imaging Library (PIL).  That is needed
for Mp area detector image display GUIs, so you will need to download
PIL separately and install it.

\textbf{Warning:}  I have not yet tested with the new LLVM-based compiler
called \textit{Clang}.  It will probably require its own separate build
target for it to work, so for now stick with GCC.

%---------------------------------------------------------------------

\subsection{Microsoft Windows}

MX can be built for almost all 32-bit and 64-bit x86 versions of Windows 
starting with Windows 95 and Windows NT 3.51.  Versions of MX running on
older versions of Windows may be missing some features (especially for
the Windows 9x series), but most core functionality still works.
At present (2013), the most commonly used version for MX is 64-bit Windows 7
followed by 32-bit Windows XP.

MX can use a variety of different compilers on Microsoft Windows.
Here they are, listed in order from most used to least used.
\begin{itemize}
  \item \textbf{Microsoft Visual C++} - The following versions have been tested
	with MX: Visual C++ 4.0, Visual C++ 5.0, Visual C++ 6.0, 
	Visual C++ 2003, Visual C++ 2005 Express, Visual C++ 2008,
	Visual C++ 2010 (currently most used), and Visual C++ 2012.
	Visual C++ 2013 has not yet been tested.
  \item \textbf{Cygwin GCC}
  \item \textbf{MinGW GCC} - Only tested with MSYS.
  \item \textbf{Borland C++} - Only version 5.5 has really been tested.
  \item \textbf{DJGPP} - This does not run on 64-bit versions of Windows.
\end{itemize}

The vast majority of build targets in MX support Unix or Posix-like programming
environments either in a self hosted or a cross-compiled system.  However,
Microsoft Windows does not.  Rather than have an entirely separate build
system for Microsoft Windows, I have chosen to require the installation of
a copy of GNU make on Windows and its associated build environment
in order to build MX on Windows, even when using the Microsoft or Borland
compilers.

Here is a list of the availables ways of providing such an environment
are listed in order from most used to least used.
\begin{itemize}
  \item \textbf{Cygwin} - The Cygwin environment is my preferred environment
	for building MX on Windows, both for Visual C++ and GCC.
  \item \textbf{MSYS} - This is a fork of an old version of Cygwin that
	is typically used with the MinGW version of GCC.
  \item \textbf{UnxUtils} - Not tested recently.  It probably does not
	run on modern versions of Windows.
\end{itemize}

I do already know about Microsoft's \textit{nmake} program.
However, the MX makefiles make heavy use of GNU make style ``include''
directives, Unix-style shell programs like \textit{cp, rm, mv} as well as other GNU make features, so supporting \textit{nmake}
would be difficult.  In case you are thinking of suggesting it,
I am totally uninterested in adding 
an entirely separate build system just for Microsoft Windows.

Given the above, setting up a build environment for Microsoft Windows is more
complicated than for any other build target supported by MX.  In the following
sections, I describe how to do that.

\subsubsection{Cygwin build environment with Visual C++ compiler}

This is probably the most common environment for building MX on Windows.
Setting up the prerequisites is a multistep process.  Many of the items
on this list are only suggestions and not required.

\begin{enumerate}
  \item \textbf{Install Cygwin from \textit{www.cygwin.com}.}
	\newline
	The basic steps for installing Cygwin are explained quite well on
	the Cygwin web site.  A few things to look out for:
	%
	\begin{itemize}
	  \item Recent releases of Cygwin provide both a 32-bit version
		and a 64-bit version.  Make sure that you are installing
		the Cygwin version that matches the 32/64-bit size of 
		the Windows version you have installed.
	  \item The Windows 9x series is not supported by the modern
		version of Cygwin 1.7.x.  But if you can find a copy of
		the old Cygwin 1.5.x, then it can be used to build MX.
	\end{itemize}

	Along with the Cygwin Base packages, I normally install the
	following optional packages on Cygwin:
	\textbf{bash},
	\textbf{binutils},
	\textbf{bzip2},
	\textbf{cpio},
	\textbf{curl},
	\textbf{cygrunsrv},
	\textbf{cygutils},
	\textbf{dash},
	\textbf{diffutils},
	\textbf{dos2unix},
	\textbf{enscript},
	\textbf{file},
	\textbf{gcc4-core},
	\textbf{gcc4-g++},
	\textbf{gccmakedep},
	\textbf{gdb},
	\textbf{groff},
	\textbf{less},
	\textbf{links},
	\textbf{make},
	\textbf{makedepend},
	\textbf{man},
	\textbf{mintty},
	\textbf{nc6},
	\textbf{ncftp},
	\textbf{ncurses},
	\textbf{netpbm},
	\textbf{openssh},
	\textbf{p7zip},
	\textbf{perl},
	\textbf{ping},
	\textbf{procps},
	\textbf{psmisc},
	\textbf{python},
	\textbf{python-numpy},
	\textbf{rebase},
	\textbf{screen},
	\textbf{shutdown},
	\textbf{subversion},
	\textbf{sunrpc},
	\textbf{tcl},
	\textbf{tcl-tk},
	\textbf{texinfo},
	\textbf{unzip},
	\textbf{util-linux},
	\textbf{wget},
	\textbf{which},
	and \textbf{zip}.
	%
	Not everything in the preceding list is strictly required, but some
	dependencies can be non-obvious.  Note that the above list also gives
	you enough packages to compile the Cygwin version of MX, but we are
	focusing on the Microsoft Visual Studio version for now.

  \item \textbf{Create Mintty Shortcut on Desktop} (optional)
	\begin{itemize}
	  \item Create a desktop shortcut to
\textit{C:\textbackslash cygwin\textbackslash bin\textbackslash mintty.exe}.
	  \item Edit the properties of the shortcut as follows:
		\begin{description}
		  \item []
			Target:
		C:\textbackslash cygwin\textbackslash bin\textbackslash mintty
			-t mintty -e /usr/bin/bash --login -i
		  \item []
			Start In: \%USERPROFILE\% environment variable
		\end{description}
	\end{itemize}

  \item \textbf{Setup /home Mount Point for Cygwin} (optional)
	\newline
	This change makes it so that user files for both Windows and Cygwin
	are saved in the same actual directory.  The following commands 
	should be executed from the Cygwin bash shell.
	%
	\begin{itemize}
	  \item Move the /home directory that Cygwin created for you from
		/home to /home.old.
	  \item mkdir /home
	  \item Add a line to /etc/fstab to mount the Windows equivalent of
		a home directory on the Cygwin /home.
		\begin{description}
		  \item[For Vista and above:]
\begin{verbatim}
C:/Users /home ntfs binary 0 0
\end{verbatim}
		  \item[For XP and before:]
\begin{verbatim}
C:/Documents\040and\040Settings /home ntfs binary 0 0
\end{verbatim}
		\end{description}
	  \item Run the \textit{``mount -a''} command to mount the Windows
		user directory at the location Cygwin expects.
	\end{itemize}
  %
  \item \textbf{/etc/passwd} (optional for SSHD)
	\newline
	Check /etc/passwd to see if it is set up correctly.  This is only
	needed if you intend to run an OpenSSH server.  Users not listed
	in /etc/passwd cannot login via the Cygwin OpenSSH server.
  %
  \item \textbf{/usr/bin/ssh-host-config} (optional for SSHD)
	\newline
	This is only necessary if you intend to run an OpenSSH server.
	\begin{itemize}
	  \item Start Mintty from its desktop shortcut by right clicking on 
		the Mintty icon and selecting ``Run as Administrator''.
	  \item Run the \textit{/usr/bin/ssh-host-config} script and give
		it the following answers.  If an answer is not specified
		in the following list, then you should use the default for
		that and press the Enter key.
		\begin{description}
		  \item [\ ] Use privilege separation.
		  \item [\ ] Create new local account ``sshd''.
		  \item [\ ] Install sshd as a service.
		  \item [\ ] Leave the CYGWIN environment set to empty
			(or maybe set it to `nodosfilewarning').
		  \item [\ ] Use the name ``cyg\_server''.
		  \item [\ ] Create ``cyg\_server'' account.
		  \item [\ ] Give ``cyg\_server'' a password.
		\end{description}
		At this point the script should end.
	  \item Start the Cygwin OpenSSH server with this command:
		``cygrunsrv -S sshd''.
	\end{itemize}
  %
  \item \textbf{Allow inbound SSH access} (optional for SSHD)
	\newline
	The following procedure is for Windows 7.  Other versions of Windows
	will be somewhat different.
	\begin{itemize}
	  \item Start the Windows Control Panel.
	  \item Select ``Control Panel \textgreater\ 
		All Control Panel Items \textgreater\ 
		Windows Firewall \textgreater\  Allowed Programs
	  \item Click ``Change Settings''.
	  \item Browse to
		``C:\textbackslash cygwin\textbackslash usr
		\textbackslash sbin\textbackslash sshd.exe''
	  \item Allow ``Home/Work'' and ``Public''.
	\end{itemize}
  %
  \item \textbf{Install TightVNC} (optional)
	\newline
	Used for remote adminstration.
	TightVNC is my preferred VNC server, but you can also use other VNC
	servers, Remote Desktop, LogMeIn, or whatever.  Here are some
	recommendations for TightVNC on how to ensure that VNC traffic
	does not flow over the Internet unencrypted.
	\begin{itemize}
	  \item Select Typical options for TightVNC, but \textbf{DO NOT}
		add a TightVNC exception to the Windows firewall.
	  \item In ``TightVNC Service Configuration \textgreater\ 
		Access Control'',
		select ``Allow loopback connections''.
	  \item When you want to connect remotely to VNC, create an SSH
		tunnel hosted on the TightVNC server computer that
		connects port 5900 on localhost (the TightVNC server
		computer's localhost) to port 5901 on \textbf{your}
		local computer.
	  \item Make a VNC connection to :1 on your localhost
		(which is really port 5901).
		If you do this, your VNC traffic will go through the 
		SSH tunnel rather than unencrypted over the Internet.
	\end{itemize}
  %
  \item \textbf{Install Virtual Clone Drive}
	\newline
	Virtual Clone Drive is freeware that comes from
	\textit{www.slysoft.com}.  This software provides a way of
	mounting ISO images as if they were CD/DVD drives.  This will be
	used for the Visual C++ installation that follows.

	If you have one, you may use a different software package to mount
	ISO images.  Alternately, if you have a \textbf{real} install DVD,
	you can just use that in your CD/DVD drive and skip installing
	something like Virtual Clone Drive.
  %
  \item \textbf{Install Visual C++}
	\newline
	Currently (2013), I normally use Microsoft Visual Studio 2010,
	but many other versions of Visual C++
	(either Express, non-Express, or Windows SDK)
	can be used to build MX.  Regardless of which version you use,
	you will only need the C/C++ compiler component and not the other
	components (Visual Basic, SQL, etc.).  MX does not make use of
	Visual Studio project files, so I normally only use the
	Visual Studio IDE for its debugger.

	If you are using an Express version of Visual C++, then this only
	provides a 32-bit version of the compiler.  This is fine on a
	32-bit version of Windows.  For 64-bit versions of Windows, you
	\textit{may} be able to get a 64-bit compiler by downloading and
	installing the Windows SDK.  You can also get a debugger by
	downloading and installing the ``Debugging Tools for Windows''.
  %
  \item \textbf{Run Microsoft Update} (optional)
	\newline
	It is strongly recommended that you install all of the updates for the
	version of Visual C++ that you installed.  This can be best 
	handled by upgrading ``Windows Update'' to ``Microsoft Update''
	and then telling ``Microsoft Update'' to update ``Other Microsoft
	Programs''.

\end{enumerate}

