<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">\documentclass[onecolumn,letterpaper,11pt]{article}

%===================================================================
\input{common_latex/common_latex_packages}
\input{common_latex/common_latex_definitions}
\input{common_latex/common_latex_help_format}
%===================================================================

\begin{document}

\begin{labcover}
\labtitle{The distcc Utility for Remote Compiling}
\vspace{0.1in}
\labdate{Fall 2017}
\vspace{0.1in}
%\labauth{Alon Yaari, ayaari@mit.edu}
%\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\end{labcover}

\wikidoc{file=PavLab.DistCC}
\wikidoc{bugz=distcc}
\wikidoc{auth=mikerb@mit.edu}


%====================================================================
\section{The distcc Utility for Remote Compiling}
\label{sec_distcc}

\app{distcc} is a program to distribute builds of C, C++, Objective C
or Objective C++ code across several machines on a network. distcc
should always generate the same results as a local build, is simple to
install and use, and is normally much faster than a local compile. 
The following instructions were borrowed and then modified for Mac OS
X from Josh Leighton at:

\urlx{https://wikis.mit.edu/confluence/display/hovergroup/Duovero+Setup}

%====================================================================
\subsection{Raspberry Pi Setup}

In the following subsections we will ensure that the correct version
of GCC and G++ are installed on the Raspbian and install
\app{distcc}. In order to start using \app{distcc} it must be setup as
the default compiler.  When compiling a program, \app{distcc} will
attempt to look for a more powerful host.  If a host is not found,
then \app{distcc} will compile locally with native compiler.

%---------------------------------------------------------------------
\subsubsection{Updating Raspbian and Installing Correct Compiler Versions}

Let's first make sure Raspbian packages are up to date.

\vspace{0.15in}
\begin{consoleverb}
 $ sudo apt-get update
 $ sudo apt-get upgrade
\end{consoleverb}
\vspace{0.15in}


\noindent 
We will install \var{gcc/g++} version 4.8. It is vital that the
compiler versions on the Raspbian for both \var{gcc} and \var{g++}
match the versions that will be used on the Mac OS X machines.  At the
time of this writing, pre-compiled versions of \var{gcc/g++} 4.8 and
4.9 are available for cross-compiling on the Mac OS X, described
below. Raspbian Wheezy, based on kernel version 3.18, by default has
versions 4.6.  Raspbian Jessie, based on kernel version 4.1, by
default has versions 4.9.  As a good middle ground we will install
\var{gcc/g++} version 4.8 as both Wheezy and Jessie suppport it.


\vspace{0.15in}
\begin{consoleverb} 
$ sudo apt-get install gcc-4.8 g++-4.8
\end{consoleverb}
\vspace{0.15in}

\noindent 
At this point the symlinks in \var{/usr/bin} point to version 4.6 or
4.9, depending on the version of Raspbian you have.  We must remove
those symlinks and create new ones pointing to version 4.8.

\vspace{0.15in}
\begin{consoleverb} 
$ cd /usr/bin
$ sudo rm g++
$ sudo rm gcc
$ sudo ln -s /usr/bin/g++-4.8 /usr/bin/g++
$ sudo ln -s /usr/bin/gcc-4.8 /usr/bin/gcc
\end{consoleverb}
\vspace{0.15in}

%---------------------------------------------------------------------
\subsubsection{Install \app{distcc}}

At this point we have ensured that \var{gcc} and \var{g++} versions
match what is available for the Mac OS X.  Now, let's install
\app{distcc} with all the proper system variables.


\vspace{0.15in}
\begin{consoleverb} 
 $ sudo apt-get install distcc
\end{consoleverb}
\vspace{0.15in}

\noindent 
Double check that the following symlinks are in \var{/usr/lib/distcc}
and if not create them.

\vspace{0.15in}
\begin{consoleverb} 
$ cd /usr/lib/distcc
$ ls -la arm-linux-gnueabihg-g++-4.8
arm-linux-gnueabihf-g++-4.8 -&gt; ../../bin/distcc
\end{consoleverb}
\vspace{0.15in}

\noindent and

\vspace{0.15in}
\begin{consoleverb} 
$ ls -la arm-linux-gnueabihg-gcc-4.8
arm-linux-gnueabihf-gcc-4.8 -&gt; ../../bin/distcc
\end{consoleverb}
\vspace{0.15in}

\noindent 
Let's ensure that when compiling that distcc is called by modifying
\var{.bashrc} to include these lines:

\vspace{0.15in}
\begin{fileverb} 
export CC=/usr/lib/distcc/arm-linux-gnueabihf-gcc-4.8 
export CXX=/usr/lib/distcc/arm-linux-gnueabihf-g++-4.8
export DISTCC_HOSTS=192.168.2.1 # replace this address with that of the desired host
\end{fileverb}
\vspace{0.15in}

\noindent The \var{DISTCC\_HOSTS} can have a white space separated list of different hoosts to try. For example,


\vspace{0.15in}
\begin{fileverb} 
export DISTCC_HOSTS=192.168.1.255 192.168.1.144
\end{fileverb}
\vspace{0.15in}

\noindent The following \var{DISTCC} configuration parameters ensure compilation happens off of the Raspberry Pi and on the more powerful slave machines.


\vspace{0.15in}
\begin{fileverb} 
  export DISTCC_BACKOFF_PERIOD=0
  export DISTCC_IO_TIMEOUT=3000
  export DISTCC_SKIP_LOCAL_RETRY=1
\end{fileverb}
\vspace{0.15in}


%--------------------------------------------------------------------
\subsection{Host Mac OS X Setup}

Compared to the Raspberry Pis, the Mac OS X machines available are
much more powerful.  The only thing needed to setup \app{distcc} is
obtaining the ARM toolchain with the corresponding versions of \var{gcc} and
\var{g++} used on the Raspberry Pis and setting up \app{distcc} as a local
daemon to accept incoming requests.

The fastest way to obtain the ARM toolcahin for Mac OS X is finding it
already compiled such as from this site:
\urlx{http://www.welzels.de/blog/en/arm-cross-compiling-with-mac-os-x/}

From within the site, choose and download the \var{.dmg} with the
appropriate \var{gcc/g++} versions.  Open and run the \var{.dmg}
installer. Specifically, we are looking for the Raspberry Pi and versions 4.8.

Add the folder where the binaries were installed to your user PATH by
adding the following to your \var{.bashrc}, \var{.profile}, or
\var{.bash\_profile}:

\vspace{0.15in}
\begin{fileverb} 
export PATH=$PATH:/usr/local/linar/arm-linux-gnueabihf-raspbian/bin 
\end{fileverb}
\vspace{0.15in}

\noindent
At this point we must make sure that when the target (in our case the
Raspberry Pi) requests a compile that the compiler names exactly
match! Our experience has been that on the Raspbian target it calls
for the compiler \var{arm-linux-gnueabihf-gcc-4.8} but the installer
provided the correct version 4.8 of \var{gcc} but named as \var{arm-linux-gnueabihf-gcc}.
 So the only thing missing from the filename is the -4.8.
So, we will create symlinks with the complete filename the target is
looking for:

Inside of the \var{/usr/local/linaro/arm-linux-gnueabihf-raspbian/bin} create the proper symlinks:

\vspace{0.15in}
\begin{consoleverb} 
 $ cd /usr/local/linaro/arm-linux-gnueabihf-raspbian/bin
 $ sudo ln -s /usr/local/linaro/arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf-gcc 
 /usr/local/linaro/arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf-gcc-4.8
 $ sudo ln -s /usr/local/linaro/arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf-g++  
 /usr/local/linaro/arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf-g++-4.8
\end{consoleverb}
\vspace{0.15in}

\noindent
Now let's install \app{distcc}.

\vspace{0.15in}

\begin{consoleverb} 
$ sudo port install distcc
\end{consoleverb}
\vspace{0.15in}

%=================================================================
\subsection{Running \app{distcc} Server on Host Mac OS X}

By default, \app{distcc} does not run as a server waiting for compile
requests.  We can start it up manually and must specify where we think
the requests will be coming from:

\vspace{0.15in}
\begin{consoleverb} 
$ distccd --daemon --verbose --allow '192.168.0.0/16'
\end{consoleverb}

\noindent
The 0.0/16 at the end allows for any range within the 192.168.x.x
subnet to connect. As of this writing, the robots are on their own
subnet and this setting will allow robots to access the distcc daemon.

Alternatively, a user can specify more strict access by using the command
\vspace{0.15in}

\vspace{0.15in}
\begin{consoleverb} 
$ distccd --daemon --allow '192.168.2.0/24'
\end{consoleverb}
\vspace{0.15in}

\noindent
The 0/24 at the end allows for any range within the subnet 192.168.2.x
to connect. 

In order to monitor proper execution observe network activity as there
should be a large spike when the target starts compiling as it is
sharing files.  On Mac, simply open Activity Monitor and switch to the
network view.

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.88\textwidth]{figures/network_activity_build_ivp.png}
  \caption{Mac OS X's Activity Monitor App.  By switching to the
    'Network' tab allows us to see the increased network activity due
    to \app{distcc} sending header files to the host to compile
    programs. }
\label{fig_uhme_overview}
\end{figure}
\vspace{0.1in}

%====================================================================
\subsection{Execution on the target Raspberry Pi}
Make sure to clean the build directories of an application you wish to
compile with \app{distcc}.  By cleaning the build directories we
ensure that \app{distcc} will be the compiler of choice.

\noindent
Perform creation of your application as normal and it should show up
as \app{distcc}

\noindent
If there is an error you will typically see:

\vspace{0.15in}
\begin{consoleverb} 
  distcc[6157] (dcc_build_somewhere) Warning: failed to distribute, running lcoally instead
\end{consoleverb}
\vspace{0.15in}

\noindent
This indicates that the daemon on the Host is either not running or malconfigured!

%==================================================================
\subsection{Monitoring Status}

\vspace{0.15in}
\begin{consoleverb} 
$ distccmon-text 2
\end{consoleverb}
\vspace{0.15in}

\noindent
The integer 2 means check every 2 seconds.

\end{document}

</pre></body></html>