SPY HILL Research
Spy-Hill.net
Poughkeepsie, New York [DIR] [UP]

Building BOINC and BOINC Applications
on Linux

This page describes the steps necessary to build BOINC (the libraries and client) and BOINC applications on Linux.
Last modified: 3 October 2009
Topics
Big Picture
Compiler
Project server
Source code
Graphics libraries
Other libraries
Configuring and building
Demo Applications
static -vs- dynamic
Acknowledgements
Overview

The Berkeley Open Infrastructure for Network Computing (BOINC) has been developed on many platforms, including Linux. Project servers are usually set up on a Linux machine, and the process of building the BOINC server software and setting up the web site are fairly straightforward. Building applications that will run on a wide range of Linux platforms presents some complications.

The main topics discussed below are:

You will likely also want to familiarize yourself with these documentation pages from the BOINC website: If you just want to install and configure the BOINC client on a Linux computer then you will want to read

Big Picture

BOINC is a complicated collection of software, in part because it actually consists of a number of separate components. Anyone who participates in a BOINC project by downloading the pre-built software is using the BOINC "client", which is the program which manages the execution of the programs being run for each of the separate projects you might join. Along with this is a separate program, called the BOINC Manager, which provides a GUI interface to monitor and communicate with the BOINC Client. On the project server there is separate server software which includes the "scheduler", which assigns work to the clients, a "feeder" which helps the scheduler communicate efficiently with the database, a "transitioner" which steps work through the various stages it has to go through go go out to the clients and come back, and then "validator" and "assimilator" daemons to process the Results once they come back to the server. On top of this, BOINC includes software for the web site, including dicussion forums for hte participants. So it's a complicated collection of software. As such, you can imagine that you need to have the right development tools to build all or part of the BOINC software, or if you are creating a project then to build your own BOINC application.

Development Tools

We began development on a machine running Red Hat 7.3, with some additional tools added as necessary. Yes, even a year ago this was an older version of Linux, but it was very stable, and in use by several high energy research projects (eg. ATLAS, LIGO). Some of the development tools turned out to be a bit out of date, so we just downloaded newer versions. That worked for the most part, until it seemed like the gcc-2.9 problem was preventing us from making portable applications.

We next moved to Fedora Core 3, which worked well but has had a few quirks of it's own.

Most recently I've been using Fedora Core 4, which had a major problem with the compiler (see below), which is now passed. I'm currently using Fedora Core 5 with no problems.

Here are some details of some past problems I've encountered. Hopefully most are fixed, but they may help you if you get stuck on something similar. (TODO: move these to another page?)

Fedora Core 3

All of the development tools (gcc, autconf, automake) that come with Fedora Core 3 work fine for building BOINC. (THIS IS NO LONGER TRUE). Be sure to also install both the libjpeg-6b and libjpeg-devel-6b packages and you won't have to worry about the JPEG libraries.

FC3 - HOSTTYPE problems

After switching to Fedora Core 3 our core client would not run correctly, which was traced to the fact that it was reporting it's type to the server as i686-redhat-linux-gnu, which is not a valid BOINC host type. Instead of "redhat" it should just say "pc". This seems to be due to GNU autoconf being very specific when it determines the host type.

There are a couple of ways to fix this. One is to edit the file config.h after you have run the configure script, to change "-redhat-" to "-pc-". The other is to specify the build target on the configure command line:

% ./configure --prefix=/usr/local/boinc --build=i686-pc-linux-gnu % make (Thanks to Peter Hallgarten for pointing out the second alterative to me.)

A change was made to the configure script on 31 May 2005 to correct this problem, but I'll leave this item in the notes just in case something similar happens in the future.

RH 7.3 - cannot find g++

Red Hat shiped two versions of the gcc compiler tools, a version they call gcc 2.96 and gcc 3.0.4, which they call gcc3. You should of course use gcc3. To do so we have found that you need to do the following during the configure and make steps: % setenv CC gcc3 % setenv CXX g++3 % ./configure --prefix=/usr/local/boinc % make

Another option is to install the latest and greatest version of the entire gcc suite of compilers, or at least gcc and g++. That is what we ended up doing, using gcc version 3.4.0. Note that for any version of gcc after 3.3 you must also install binutils version 2.13 or later.

RH 7.3 - gcc-2.96 warning!

It seems that Red Hat 7.3 may have a fatal flaw as a build platoform: gcc-2.96. The trouble is, there never was an official gcc-2.96, this was just something that Red Hat created. And they created compatibility libraries using it to link code built for Red Hat 6.x. And if you build something on a machhhine with this installed it's possible that your code will link against this library and not be usable on any other Linux computer, even if you built with gcc3. Ugh!

GNU autoconf and automake

To configure the BOINC software to compile properly you currently need GNU autoconf version 2.59 or newer and GNU automake version 1.9.3 or newer. The versions distributed with Fedora Core 3 are fine, but the versions in RH 7.3 were too old, so we had to get the latest source distributions of autoconf and automake and build them ourselves.

As with all GNU tools, building the latest autoconf and automake was very easy. You can get the latest source code from ftp://ftp.gnu.org/pub/gnu (under the autoconf and automake directories). Building automake 1.9.3 requires autoconf 2.58 or better, so you will have to build and install autoconf before you build and install automake. Just unpack somewhere and cd into the top level source directory, say `./configure` and then `make`. Finally, as root say `make install`. The binaries are installed in /usr/local/bin, so be sure that this is listed ahead of /usr/bin in your PATH so that they take precidence over any "system" versions of these tools.

Server Software

If you are just building applications then you just need the gcc compiler and the graphics libraries, as described above and below. If you are setting up a server then you also need the apache web server and a the mysql database server. More detailed software prereqisites are listed on the BOINC page

Python version problems

Red Hat ships two versions of the python script processor, apparantly because a large number of their installation and system adminstration scripts use Python 1.5, while everybody else these days uses Python 2.2 or better. If you give the command python you are actually getting Python 1.5. You have to say python2 to get the later version.

we tried making /usr/local/bin/python a link to python2 but we were not sure this was the best approach. So we downloaded the latest Python source (version 2.3.4) and built it and that worked fine.

MySQL-python

The python interface to the MySQL database requires the additional DBI module MySQL-python. We downloaded it and installed with python setup.py install and there were no problems

Source Code via CVS

This is old. BOINC now uses SVN not CVS Details to follow...

Graphics Libraries

To build BOINC applications which display graphics, either as a screensaver or in a separate a graphics window, you will need to have various graphics libraries available.

To build an application on Unix you will need the JPEG library, a few other image libraries now distributed with BOINC, and the OpenGL and GLUT graphics libraries.

To build the BOINC Manager (the user interface for communicating with the core client) you will also need wxWidgets, but this is not required for just building a BOINC application.

JPEG Library

BOINC's graphics capabilities include being able to display JPEG image files as "texture maps" in OpenGL. Even if you do not use this feature, you need to have the JPEG library on your build machine so that the compiler can link against it. On many Linux distributions you just need to install the JPEG library and developer packages. As an alternative, you can download and build from the original sources.

This section is old and out of date, but still better than nothing.

OpenGL and GLUT

BOINC uses GLUT, the GL Utilities Toolkit, which in turn uses OpenGL and GLU (the GL Utility library). On Red Hat 7.3 the X11 distribution (XFree86) comes with OpenGL (actually the Mesa implemntation) and GLU. You can also install glut as a dynamic library, but ...

on Linux uses OpenGL, along with GLU (the GL Utility library), GLUT and GLX (the OpenGL extensions for X11). Some of these come with the Linux distribution or X11 distribution, but some are distributed only as dynamic libraries, and you will likely want to build static versions of them so that your application can run on a wider range of Linux platforms.

But there are some complications... It seems that you will want to use some of the dynamic libraries, because they will be appropriate for the particular X11 installation and graphics card for the platform on which the application is run.

The GL library comes with the XFree86 distribution. It is a dynamic library. But that is okay, because it should be built with the rest of your X11. The same goes for GLU.

GLUT is another matter. I have downloaded glut-3.7.6 and succesfully built the static library on RH 7.3 with gcc-3.4, but the same build failed on RH 7.3 with gcc-3.3. I'm not sure why.

So now I am trying a slightly older version which I think has worked, glut-3.7.

While I found glut-3.7 easiest to use on Linux, I found freeglut easier on Windows. But that's a different web page...
End of the sketchy part on OpenGL

wxWidgets

The BOINC manager uses wxWidgets to provide a unified Graphical User Interface (GUI) which is for the most part the same on all platforms (Windows, Mac, Unix) but which also follows the user interface conventions of the particular platform when there are differences. You do not need wxWidgets if you are just building BOINC applications, but you do need it if you are going to build the BOINC Manager, which is a part of the BOINC client (the part that goes out to people's PC's). Unless you are working on the client source code, the best thing to do is just download a pre-built client package from the BOINC download site.

To install wxWidgets you first need to get the code from www.wxWidgets.org. The latest version of BOINC requires version 2.6.0 or later of wxWidgets.

WxWidgets on Unix makes use of the windowing features of of GTK, the GIMP Toolkit, though you can also build it to use just the Motif library. (A distribution of 2.6.1 was created which works with X11 without GTK or Motif, but this is classified as "beta" and there is not a newer version.) You should use the GTK version. The latest version of wxWidgets requires GTK+2 and no longer supports GTK+ version 1. Also, GTK in turn requires that several other tools be installed, such as pango and ...

pango, .... (I forget what else- find these...)
So you will need all of these installed, either the development versions or source packages, just to build wxWidgets. Complete build instructions are included in the file README.txt.

Because the wxWidgets library is likely not on the client machines, you need to build the "static" version of the library, which is not the default. It's also easiest if you build it all as a single library. The basic configuration command for this is 

       configure --disable-shared --with-gtk --enable-unicode
but see the file INSTALL.txt in the distribution and try configure --help for further details.

If you find that the BOINC configuration script is not finding wxWidgets, even though you know it has been installed, then you should check that it was built with the flags above.

Other Libraries

A few other libraries are needed to build BOINC. The latest versions of the Fedora Core distribution have new enough versions of these packages, but you need to make sure they are installed, and if you have problems with them then you may need to download and build from source.

curl

BOINC uses cURL for communication between the server and clients. You will need a current version of the cURL library if you are buiding the client software on Linux or Mac. You do not need cURL to build the server software (the Apache web server takes care of that end of the interaction.)

If you do not have a recent enough version of cURL installed as a part of your Unix distribution then you will need to build it from source. The main page for cURL is at http://curl.haxx.se More details on how cURL is used in BOINC can be found here.

openssl

The cURL library uses openssl for secure communication (as in 'https'). Although most BOINC interactions are not via a secure link, you need a current version of openssl to build cURL. If you ever find while running the BOINC configure script that it says you do not have a new enough version of cURL when in fact you do then the problem may be that openssl needs to be updated. But it won't tell you that.

Configuring and Building BOINC software

This part of the process is fairly straightforward. Once you have unpacked the software, or updated from CVS, you set up the configuration by giving the command 
 _autosetup
Be advised that this script, not the configure script, creates the version info in version.h.

After that, say ./configure followed by make.

[a few minor notes on nuances could still go here]

Demonstration Applications

BOINC comes with several example programs which help you learn how to code BOINC applications. I have also found it useful to write my own exercises as I go along, and I have tried to be liberal with helpful comments. If you are new to BOINC, the easiest way to learn to write applications which do various useful things, including graphics, is probably to work your way through these applications in the order listed here: Note that the BOINC distribution also includes an application called "1sec". This seems to be used for testing the initial build of the BOINC software, but it is not a complete and functioning BOINC application. Do not waste your time trying to get it to run on your BOINC project.

Building static apps on Unix

An application program built on one version of a Linux distribution (eg. Red Hat 7.3) with dynamically loaded libraries may not run on other versions of Linux because of a mis-match in library versions, or because a particular library is not installed on the remote client. So we have built all of our apps static, so that they do not use dynamic libraries. This makes the executables a bit larger, but to compensate we have made sure to strip them of extra debugging information.

For graphics some libraries need to be dynmaic, so this is overly simple and needs to be revised! Will do so soon as I get it all straight. See the Makefiles in the example applications for examples of what works so far...

To compile the BOINC client and apps static you should set the LDFLAGS environment variable appropriately before you run the ./configure script:

% setenv LDFLAGS -static % ./configure prefix=/usr/local/boinc

An example of stripping an executable is

% strip boinc_4.66_i686-pc-linux-gnu

Acknowledgements

What I have recorded here has come from many sources. First, from my own experience building BOINC and BOINC apps "from the ground up". I've had to do this in my own slow way so that I would understand how it all works, even when others (below) have figured out something first.

I also gratefully acknowledge help from David Anderson, Rom Walton, and the others who have created BOINC and the documentation pages that go with it. Although I sometimes find the official documentation incomplete I don't hold that against these guys. BOINC is still developing (and hence I'm aiming at a moving target) and so the documentation is evolving and filling in as we go. These guys have accomplished a heck of a lot for a few overworked people.

Next, the Einstein@Home development team, consisting mainly of Bruce Allen, Bernd Machenschalk, Reinhard Prix, Steffan Gruenwald (and myself). Bernd has written very complete though sometimes terse notes on how to build BOINC and the Einstein@Home application on Windows. Reinhard is a wizard of GNU autoconf and automake, and he coded the instruction to build the complicated Einstein@Home application on Linux, including the static/dynamic library dependencies. Bruce has managed the project and wrapped his mind around all things BOINC in addition to his knowledge of the LIGO software for Einstein@Home. He has made numerous important observations and directed the team to solving a number of problems.
  Copyright © 2009 by Spy Hill Research https://www.spy-hill.net/~myers/help/boinc/boinc-on-linux.html (served by Islay.spy-hill.com) Last modified: 03 October 2009