Building BOINC applications

When building a BOINC application, you typically

• want versions for several platforms (Windows, Mac OS X, Linux);
• want each version to run on a wide range of volunteered computers (e.g. the Linux/x86 version should run on Linux systems of many ages and types).

Achieving these goals can be challenging. However, BOINC provides tools and example files that simplify the task.

Whether you're creating a new application or adapting an existing application to BOINC, we recommend that you start by building the BOINC sample application example_app on all the platforms you want to support. When this is done, you can use the example application and its associated project files as a basis for your own application.

The first step in building the example application on a given host is to check out the boinc and boinc_samples modules on that host. Put them in the same parent directory.

Windows

We use Windows XP for builds (other Windows versions may work too).

Microsoft Visual Studio

Go to boinc_samples/win_build. If you're using Visual Studio 2005, open samples.sln. If you're using Visual Studio 2003, open samples_2003.sln. Select 'Build/Build? Solution', or hit F7. That's it!

There is a free version, ​Visual C++ 2008 Express Edition, which works with the BOINC project file (after it is converted). You'll also need the ​Microsoft Platform SDK and some ​changes to your Visual Studio Express installation to include the SDK. Warning: you cannot use more recent versions of the SDK (which do not include glaux).

If you use your own project file:

• It must compile BOINC .C files as C++. To do this: in Properties, see C/C++ -> Advanced -> Compile As.
• If your application uses graphics, go to Properties -> Linker -> Input. In Delay Loaded DLLs add

  GDI32.DLL;OPENGL32.DLL;GLU32.DLL
  

  and in Additional Dependencies add

  delayimp.lib
  

• Configure your project to use ANSI strings rather than Unicode.

Cygwin

Cygwin is an alternative to Visual Studio for building Windows apps. In order to run a cygwin application from BOINC, you need to supply all the cygwin DLLs that the application requires in addition to the executable. You can get LISTDLLS from ​http://www.sysinternals.com/. It will tell you what DLLs a running executable has loaded.

TODO: links to required software?

TODO: develop a Makefile for building example_app under Cygwin. It can assume that the libraries in boinc/lib and boinc/api have already been built. Verify that _autosetup/configure/make work in boinc/.

Information from CERN is ​here.

Symbol Stores

Introduction

In order to obtain useful diagnostic information in the event of an application crash, it is necessary to dump a callstack and any other relevant information about what was going on at the time of the crash. Symbols are only needed during a crash event, therefore they are stripped from most applications to cut down on the binary size and bandwidth requirements to deploy a new release.

Without symbols, callstacks tend to be nothing more than a list of function pointers in memory. A developer has to load the un-stripped executable in memory using the same operating system and similar processor to jump to that memory address in order to determine the function name and parameters. This is very labor intensive and generally not a very fun job.

Microsoft created a technology called a 'Symbol Store' to use with their debugger technology which allows Windows debuggers to locate and download compressed symbol files to diagnose problems and convert function pointers into human readable text. This greatly speeds up the process of diagnosing and fixing bugs.

With the BOINC Runtime Debugger for Windows framework a project can publish their symbol files and only have to distribute the application to each of the BOINC clients. When a crash event occurs the runtime framework will download the symbol file from the symbol store and then proceed to dump as much diagnostic information as possible to help projects diagnose the failure.

Requirements

You'll need the latest stable release of the ​Debugging Tools for Windows.

Verify that your executable is setup to generate PDB debugging symbols for a release build.

Verify that the advance linker option to generate a checksum is enabled for a release build.

You'll need to explicitly name both your EXE and PDB before compilation since the debugger bases the name of the PDB file off of information that is stored in the executable header.

Project Symbol Store

Specifying a project wide symbol store is as easy as adding the symstore element to your config.xml file for the project.

Below is an XML shred with an example symstore element.

<boinc>
    <config>
        <symstore>http://sample.example.com/symstore</symstore>
    </config>
</boinc>

Adding symbols to the symbol store

​Symstore is a utility to manage symbol stores. You'll want to create a local symbol store on your Windows build machine in which you'll initially add new symbol files with each revision of your application.

Symstore will compress the symbol file and then copy it into your local symbol store.

Below is an example command which you can run from the Windows command line or cygwin command line.

symstore.exe add /l /f c:\SampleSrc\*.pdb /s c:\symstore /compress /t "Sample" /v "5.02" /o /c "Application Release"

Uploading symbols to the symbol store

Most projects tend to use scp to copy files between Windows machines and their project server.

The example below copies the entire symstore to the target location. After the copy operation you can delete all the subdirectories except '000Admin' to save time uploading for future application symbols.

pscp.exe -r -C -batch c:\symstore sample@project.example.com:projects/sample/html/user/symstore

Mac OS X

Instructions for building applications on Mac OS X are on a separate page.

Linux/x86

If you build an application on a recent Linux distribution, it won't run on older Linux distributions because of library incompatibilities. The only solution we've discovered is to build applications on a host with an old Linux and an old gcc. Setting up such a host, however, is a giant pain.

Our recommended approach is not to build directly on a Linux host, but rather:

• Install ​Microsoft Virtual PC 2004 on a Windows XP machine (preferably one that's fast and has lots of disk).
• Download the Compatibility virtual machine module. This is a Debian Linux system with the appropriate (old) version of gcc.
• Run this system under Virtual PC.
• Install the boinc and boinc_samples modules in the same parent directory on the virtual host.
• Build the BOINC libraries: go to the boinc/directory and type

  _autosetup
  ./configure --disable-client --disable-server
  make
  

  Do not 'make install'.
• go to the boinc_samples/uppercase directory and type

  ln -s `g++ -print-file-name=libstdc++.a`
  make
  

Other UNIX systems

• Software prerequisites
• configure/build

GLUT notes

Freeglut 2.2, freeglut 2.4 and OpenGL Utility Toolkit (GLUT) libraries are supported.

X11 notes

To get the X11 support, select the relevant options when you're installing Linux, or (Redhat) go to System Settings/Add? Software.