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

Building BOINC and BOINC Applications on MacOS X

These notes describe how I have built BOINC applications on MacOS X (aka Darwin), primarily using command line tools such as 'configure' and 'make' rather than using XCode.
Last modified: 03 October 2009
Topics
Software Prerequisites
Developer tools
Source code
Graphics libraries
Configuring and building
Demo Applications
The Berkeley Open Infrastructure for Network Computing (BOINC) has been developed to run on many platforms, including Unix, Windows, and Mac. These notes describe my experience building BOINC applications on MacOS X (which uses a Unix variant called Darwin).

There are actually two ways to build BOINC and BOINC applications on a Mac, the XCode GUI method (Graphical User Interface) and the CLI method (Command Line Interface). The XCode GUI method is documented at http://boinc.berkeley.edu/trac/wiki/MacBuild. The notes presented here document the Command Line method.

My intent is to be complementary to the GUI method, and is aimed at making the process as similar as possible to what is done on Linux (and possibly, eventually, Windows using Cygwin). Given that, you may also want to take a look at my notes on Building BOINC and BOINC applications on Linux. You may also want to read the notes on the XCode GUI method even if you intend to use the CLI method. In both cases you still have to install XCode.

Here are the main points you need to consider to build BOINC applications on MacOS X via the CLI method:

Software Prerequisites

The software you will need to have installed in order to build BOINC depends upon what you intend to do. If you are setting up a BOINC project you will need to build the server software, which will require development tools such as GNU autoconf and automake, libtool, pkg-config, libcurl, and OpenSSL. If you just want to build BOINC applications you only need the development tools. To get the complete list of requirements, with version numbers, see the

The following documentation from the BOINC website may also prove useful:

Developer Tools

By default Macs do not come with a compiler or other developer tools. You will have to install these first before you can build anything. Apple provides a suite of tools called "XCode", but you will also need to install some additional tools from GNU or other sources. You can do that using Fink, or download and build from source directly.

Fink

One very easy and useful way to install supporting Unix software is with Fink. The Fink Project modifies existing Unix software so that it compiles and runs on Mac OS X, and then they make it available as a coherent distribution using Debian tools like dpkg and apt-get. You can use Fink via the command line very much like you would use apt-get, or there is a separate GUI interface called Fink Commander. If you are already used to working with Unix you will find Fink very useful for installing your favorite tools.

But note that you do not have to use Fink if you do not want to. Instead, you can simply download and build each of the tools below from source code (links to the source are provided).

If you use Fink you will want to know that it installs everything under /sw, and executables are in /sw/bin. You will need to put this in your shell PATH to use those executables. The easiest way to configure your shell is to check for the file /sw/bin/init.csh (for C-shell) or /sw/bin/init.sh (for Bourne shell) and `source` it if it exists. Be warned, however, that this script pre-pends /sw/bin to the PATH, which means that Fink versions of packages will be used in place of those built from source and put in /usr/local/bin.

And alas, sometimes the versions of packages which are available via Fink are not current enough for BOINC (this is currently the case for libcurl). In that case the only thing you can do is download and build from source. And given the warning about paths above, you should be sure to uninstall any package in Fink which does not meet the minimum requirements for BOINC.

XCode

The Apple developer tools are called "XCode", and can be downloaded from http://developer.apple.com/tools/download/. You will need to get an account with the Apple Developer Connection (it's free) and login to ADC to download the tools. Use XCode 1.5 for Panther (MacOS 10.3) and use XCode 2.0 for Tiger (MacOS 10.4).

The file you download will be a disk image which will mount on your desktop. Double-click on "XCodeTools.mpkg" and follow the Installer dialogue to install the basic set of developer tools.

To build applications which are backward-compatible to earlier versions of MacOS X you also need to install the optional CrossDevelopment package. To do so open the "Packages" folder in the XCode disk image and double-click on CrossDevelopment.mpkg to install the appropriate SDKs. This is not done by installing the overall development package.

You must install XCode to build BOINC, even if you are not going to use the GUI interface, because this is the only way to install the compilers, headers and other development code necessary for building apps which can run on a Mac.

GNU automake / autoconf

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 XCode are too old, so you will need to somehow get newer versions. There are two easy ways to do this.
  1. Using Fink, either via Fink Commander or the command line, install the newest versions of automake and autoconf.

  2. Obtain the source code for both directly, from ftp://ftp.gnu.org/pub/gnu (under the autoconf and automake directories) and build and install from source.

    Like all GNU tools, these are easy to build and install. 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 the older versions installed with XCode.

    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.

pkg-config

You also now need pkg-config. You can either
  1. Install via Fink, where the package name is "pkgconfig" not "pkg-config", or
  2. Download it from http://pkgconfig.freedesktop.org/releases/

cURL and OpenSSL

Building BOINC also requires cURL (actually the library, libcurl) and OpenSSL. Unfortunately libcurl is not included with XCode, and the version available via Fink is too old. You will therefore need to build from the source code, which you can obtain from http://curl.haxx.se. Building and installing are easy and follow the standard pattern of configure/make/make install.

OpenSSL (is the Fink version new enough?) ...

I have found that sometimes the BOINC configuration script complains of a problem with curl when the real problem is that OpenSSL is not current.

BOINC Source Code

In the past BOINC used CVS for source code version control, but they have recently switched over to using Subversion (SVN) . While CVS is a part of XCode, Subversion is not. You will therefore need to install Subversion yourself. There are three different ways to do this, as described here, and any will do the job. If you are using Fink it helps to know that the package you need to install is called "svn" rather than "subversion".

To use Subversion to check out the BOINC source code and sample applications, first change to a working directory and give the commands 

svn co http://boinc.berkeley.edu/svn/trunk/boinc
svn co http://boinc.berkeley.edu/svn/trunk/boinc_samples
A roadmap of the BOINC directory tree can be found at http://boinc.berkeley.edu/trac/wiki/SourceCode

Even though BOINC is now using SVN, you may need CVS to obtain sample applications or for working on an application with other developers. I found a small problem with CVS on Macs which may or may not still exist, and may be a problem for you (but likely not). CVS version 1.10 is distributed as a part of XCodeTools 1.5 (for Mac OS 10.3) , and that worked fine with the BOINC CVS server when BOINC used CVS. But the CVS server used by the Einstein@Home developers for their application development needed CVS 1.11, so I had to install a newer version of CVS using Fink.

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. It turns out to be easiest in the long run to get the source code for these libraries and compile them yourself so that you can link against them statically, which makes your application transportable to a wider variety of platforms.

To build an application 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 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. Unfortunately the JPEG library is not installed by default on MacOS X, and does not come with the XCode developers tools. There are two ways to get the library, either via Fink or by building from source code:

Other image "libraries"

BOINC uses two other "image libraries" for "bitmapped" images and TARGA images. Until recently these were not a part of the BOINC distribution. They were a part of the SETI@Home application code, and you just had to know that in order to get and use them.

More recently, the files bmplib.C and tgalib.C and their associated header files have been added to BOINC in the api directory. If you build your application with these files included (and their associated header files) then you will be able to use those file formats for texture maps. You don't need to build these as separate libraries, as is done for the JPEG library.

wxWidgets

The latest version of the BOINC core client uses wxWidgets to provide a unified API for the GUI interface. You do not need this if you are just building BOINC applications, but you do need it if you are going to build the BOINC Manager, which is the separate Graphical interface program for managing the Core Client. You will probably only need to build the Manager or Core Client if you are working on BOINC development. Otherwise, just get the pre-built versions 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.8.3 or later of wxWidgets. Unpack the bundle and configure with 

  ./configure --disable-shared
Edited so far to here...

(more details here, I'm not done with this yet...)

OpenGL and GLUT

BOINC uses OpenGL for graphics, and on Unix/Mac it also uses GLUT, the GL Utilities Toolkit. You'll need to set up to use OpenGL and GLUT, and I don't know yet how this is done on the Mac (but I think it's in Charlie's notes..) 

	  (more details here, I'm not done with this yet...)

Configuring and Building BOINC software

To configure BOINC on MacOS X you need to add a few extra command line arguments, but otherwise the build is just as on Linux. (You can also build using the Developer tools, as Charlie Fenton has. I've not tried it so I won't report on it here until I do.)

To configure to build BOINC after you have checked out the version you want from CVS use something like: 

./configure --prefix=/usr/local/boinc --disable-client --disable-server \
            --with-apple-opengl-framework CPPFLAGS=-I/sw/include LDFLAGS=-L/sw/lib

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.

In general, you should build your application on the "oldest" platform which you wish to support. So if you want your application to work on both Panther (10.3) and Tiger (10.4) then build on a Panther machine.

If you happen to build on Tiger then you may see the app failing on a Panther machine with an error code 5 ("unknown error") and output returned for stderr which looks like: 

<core_client_version>5.4.9</core_client_version>
<message>
process got signal 5
</message>
<stderr_txt>
dyld: hello_5.07_powerpc-apple-darwin Undefined symbols:
hello_5.07_powerpc-apple-darwin undefined reference to _statvfs
expected to be defined in /usr/lib/libSystem.B.dylib

</stderr_txt>

Charlie Felton's instructions may have information about how to build on Tiger in a way that your application runs on Panther, but I've not yet digested it.

Acknowledgements

Much of what I have recorded here has come to me 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.

Next, David Anderson, Rom Walton, and the others who have created BOINC and the documentation pages. I will be the first to point out that the documentation is incomplete, but 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.

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.

Charlie Feltons's notes on Building BOINC Manager with embedded Core Client plus libraries libboinc.a and libboinc_graphics_api.a were very useful for figuring out how to build the newest client software with the screensaver.
  Copyright © 2009 by Spy Hill Research http://www.Spy-Hill.net/~myers/help/boinc/boinc-on-darwin.html (served by Islay.spy-hill.com) Last modified: 03 October 2009