SPY HILL Research Spy-Hill.net


Poughkeepsie, New York [DIR] [UP]

Building BOINC applications on Windows


These notes describe the development environment and additional steps I've used to build applications for the Berkeley Open Infrastructure for Network Computing (BOINC) on a Windows system.

Last modified: 04 September 2011
Topics
Compiler
Source Code
Libraries
Applications
Troubleshooting
Acknowledgements
The Berkeley Open Infrastructure for Network Computing (BOINC) has been developed on many platforms, including Window, Unix, and Mac. These notes describe the development environment and additional steps that I have used to build BOINC applications on Windows 2000 using Microsoft Visual C++ 7.

This is not the only way to build BOINC applications on Windows. Bernd Maschnschalk of the Albert Einstein Institute (AEI) has worked out a CLI environment for building BOINC and the Einstein@Home application on Windows. I will link to his notes here when I find the right place to link.

Please note that this web page is always in development as BOINC evolves and grows, and in any case the information here may be somewhat out of date. I hope it is still somewhat useful. At some point in the future I hope to break this page out into many smaller pages for particular topics.

The main topics discussed below are:

You will likely also want to familiarize yourself with these documentation from the BOINC website on:

There are now two BOINC documentation wiki's under development:

Compiler

There are a variety of different options for compiling BOINC code on Windows. You can buy the commercial Microsoft Visual C++ compiler (MSVC++). You can download the free "Express" version of MSVC++ (and the SDK that goes with it), or you can use the Unix-like Cygwin environment. It is also possible to use the "bloodshed" tool to build BOINC on Windows, but I don't yet know much about this. My experience is with the first, so my documentation for it is more complete, but I will try to fill in notes on the others as I learn more about them myself.

MS Visual C++

I started with Microsoft's Visual C++ version 7 (also known as MS Virtual Studio 2003), which is a complete IDE (Interactive Development Environment). At first it looked like I would need to purchase the entire Microsoft Developer Studio at a price of about $1000, but it turns out I was able to buy just MSVC++ for about $129. They even sent it via overnight delivery.

Mircosoft also make available a free "Express" version of their compiler. o There is a newer MSVS 2005, which contains Visual C++ version 9. It isn't possible (at least without editing config files by hand) to build using VS 2005 and files from VS 2003. More on that below.

I come from a Unix background, so it took me a while to get used to the GUI interface and the different lingo, but it's not that complicated. If you are familiar with "Makefiles" in Unix you will find something similar in MSVC++, but it's not quite the same because it's menu driven.

In the MS IDE each executable or library which you build is called a "Project", and a collection of related projects is called a "Solution". You can use the IDE tool to build just one project at a time, or all of the projects in the same solution.

The easiest way to learn to use the interface, if you don't know it already, is to use the examples provided with the sample applications below. Just double click on the solution file (ends in .sln) to launch it. Then right click on the project or solution name and select "Build" to build the project. Or you can first select "Properties" to change any of the properties before you build.

Microsoft's compiler gives you the option of building your application using the .Net framework, and with MFC, the Microsoft Foundation classes. For distributed applications you do not want to do this, because not all Windows boxes out there support .Net or MFC. So in selecting your build options choose "without MFC". This is already the default in the demos.

Note that if you create your own project file:

MS Visual C++ "Express"

As an alternative to buying MS VC++, one can now also download from Microsoft an "Express" version for free. This is not without some complications. The express version is designed to encourage developers to build .Net applications, so that is the default. To build applications that can be distributed to all Windows platforms, even those without .Net, you will need to download and install a separate Microsoft Platform SDK. Instructions for this can be found at
http://lab.msdn.microsoft.com/express/visualc/usingpsdk/default.aspx
(Thanks to Greg Steffensen for noting this. I will try to verify it myself in the future.)

Finally, note that before you can build the sample applications below you will need some extra libraries, as described below.

Cygwin

Bernd Maschnschalk of the Albert Einstein Institute (AEI) has worked out a CLI environment for building BOINC and the Einstein@Home application on Windows using Cygwin. I don't know much about this, but I'll try it out at some point, and also try to link to notes on it when I can. Since Cygwin provides a Unix shell and other tools on the Windows platform the build proceedure is more like Unix than using the MSVC++

Bloodshed

Bloodshed is another Interactive Development Environment (IDE) tool which works on Windows. I've not yet tried it out. More information is at http://www.bloodshed.net. I will try to record here anything useful I learn about it.

BOINC Source Code

BOINC is currently in active development, so the source code is constantly changing. The developers try to keep the development branch stable, but as new features are added or bugs are fixed some new problems may arise. Current efforts are primarily directed at improvments to the client, so you should find that the server code and libraries are fairly stable.

You can get the BOINC source code via Subversion. Instructions may be found on the BOINC web site: Getting source code . For building applications it is best if you check out the "server_stable" branch. Avoid the trunk, as it contains new and often untested code.

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 Manager you will also need wxWidgets (see below), but this is not required for just building a BOINC application.

OpenGL and GLUT

BOINC graphics are based on OpenGL, a standard library for graphics which is now implemented in hardware in many graphics cards. OpenGL comes with Windows, and support for using it comes with MSVC++.

BOINC also uses GLUT, the GL Utilities Toolkit, which does not come with MSVC++, so you will need to get GLUT and build it yourself. There are potentially three separate versions of GLUT you might choose from:

For Windows I have had the best success with building freeglut from source. Here are the main steps:

I've also been able to get graphics programs to run on remote client hosts by including the dynamics library (GLUT32.DLL) in with the application (as a "bundled" application) . But to insure that the program can run on any computer it is certainly easier to link against the static library.

Delayed loading of dynamic libraries

On Windows all BOINC applications now attempt to load graphics libraries dynamically, and fail gracefully if this is not possible. This means that the computation thread can continue even if the graphics thread crashes or fails to start. For this to work one must specify that loading of the graphics dynamic libraries be delayed. This is done in MSVC++ on the "Properties" page, in the "Linker" section, under "Inputs". Enter the names of the libraries to delay loading, separated by semicolons, as
     GDI32.dll;OPENGL32.dll;GLU32.dll
A sign that you have forgotten this is an error message when linking which says something like
     unresolved external symbol __HrLoadAllImportsForDll@4 reference in...

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. I have tried using pre-compiled version of the JPEG library, but with limited success. This is I have found it easier to just build the library from source (easier once you have the steps laid out, as they are below). Keep in mind that the library code was written in 1998. It still works just fine, but the process for building the library has changed as development tools have changed.

So here is how to build the JPEG library using MSVC++ 7:

  1. First, get the source code. While you may find the code in various places on the Internet, I have found it easiest to get it via the Independent JPEG Group website. Note that this is not the same as the ISO JPEG Standards committee (www.jpeg.org), which does not distribute code. The code available from the IJG is a gzip'd tarball, which is great for Linux but not very useful for Windows. There is also a link on the IJG group to a zip file packaged specifically for Windows. The direct link is ftp://ftp.simtel.net/pub/simtelnet/msdos/graphics/jpegsr6.zip This will unpack all the code and documentation into a folder called jpeg-6b.

  2. Next, create jconfig.h for your system. For a Windows machine using MS Visual C++ copy the file jconfig.vc to a file called jconfig.h in the same folder.

    (If you are not building on Windows with MSVC++ then you can try another one of the sample files in the source distribution. See the documentation in the file Install.doc for details.)

    The installation instructions in Install.doc also tell you to copy a Makefile, but you don't need to do that. Instead....

  3. Get the MSVC++ "solution" and "project" files for building the JPEG library. I have created the following up-to-date solution and project files: jpeg-6b.sln and jpeg-6b.vcproj. Right-click on these links and save them in the jpeg-6b folder with the rest of the source code.

  4. Now build the library. Launch the solution file (double click on it), right click on "jpeg-6b" and pull down to "Build". If there are no problems you should quickly see
        Build: 1 succeeded, 0 failed, 0 skipped
    in the Output window.

    The compiled library is the file jpeg-6b.lib in the Debug subfolder.

    (The solution file provided here creates a static library, which is what you want for a BOINC application which will be run on various varieties of Windows. However, if you want to change any of the build parameters then right-click on "jpeg-6b" and pull down to "Properties".)

  5. Finally, install the library and header files on your system. You can put these anywhere, as long as you reference them correctly in the solution file for your application, but I recommend some organization.

    I put the library file in C:\lib. You may have to create this folder first. Once it exits, just drag jpeg-6b.lib from the Debug subfolder to the C:\lib folder.

    I put the header files in C:\include\jpeglib. You may want to put them somewhere else. In any case, you may have to create the folder first. Once it exits, copy the following files to it:

            jpeglib.h       jconfig.h       jmorecfg.h      jerror.h
    
    To get my BOINC applications to build on MS VC++7 I found I had to edit the file jmorecfg.h in two places, to comment out the definitions of the macros INT32 and FAR.
Once you have installed the JPEG library and header files you will need to have your projects properly reference them. For each project in a solution you need to right-click and pull down the "Properties" item. Then do the following:

One more thing. The JPEG library is pure C code, and the solution file linked above builds it as such. BOINC is C++ code. For it to compile properly against the library the header file jpeglib.h must be included in a "C" context. The code for this looks like:

   extern "C"{
   #include "jpeglib.h"
   }
Unfortunately, the latest version of gutil.C has the first and last lines of this commented out, probably because someone probably built their version of the JPEG library with C++. Until this is fixed you will need to uncomment these lines yourself.

I also note that the version of jpeglib.h I'm using on Red Hat Linux 7.3 has this extern "C" already built into it, so this isn't needed on Linux.

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 (though you could).

Even more recently, some of the code for dealing with "texture" bitmaps was moved from the file gutil.C into a separate file texture.C (and header file texture.h). If you are building an application that has not been updated in a few months you may want to check that it includes these files in the list of source files.

wxWidgets

BOINC now uses wxWidgets to provide a unified API for the GUI interface. The graphical "look and feel" of BOINC is therefore the same on Windows, Mac, or Unix, with only small variations to match the conventions of the particular platform. So to build the BOINC Manager you need to get and build the wxWidgets library, and set up your build environment to use it.

You do not need wxWidgets if you are just building BOINC applications. So unless you are working on developing code for BOINC itself (not an application) or on a custom built Client setup, you can more easily download the latest pre-built versions of the BOINC Client and Manager from the the BOINC download site.

To install wxWidgets you first need to get the code from www.wxWidgets.org. The current version of BOINC requires version 2.6 of wxWidgets. The easiest way to get the code is to download the executable installer (setup.exe) and run it, but you can also unpack the source from a .tar file if you wish. (The installer just unpacks the source code, it doesn't build it.) Either way, you should have the package installed in a path without spaces in the name! Mine is at F:\src\wxWidgets-2.6.3 on one machine, and C:\wxWidgets-2.6.1 on another.

Installation instructions for Windows can be found in the file docs\msw\install.txt. Basically, with MSVC++ you open build/msw/wx.dsw (which just has the name "wx" in the file browser) and build all of the 18 Projects in the Solution. You should build the 'debug' configuration of the library, since that is what the BOINC Project for boincmgr will look for.

If you are using MSVC++, as I am, then you will need to define one system environment variable, called WXWIN, which points to your installation of wxWidgets. To do so:

  1. Open up the Control Panel (via Start -> Settings) and launch the "System item".
  2. Select the "Advanced" tab and then press the button labeled "Environment Variables..."
  3. In the "user variables" section add a new variable with the name WXWIN and the value F:\src\wxWidgets-2.6.3 (or whatever is the path to the top level of you wxWidgets build).
You can, if desired, build the BOINC manager against a different version of wxWidgets just by changing this variable to point to the installation directory of the other version. In any case, restart MSVC++ after creating or changing the WXWIN environment variable for it to take effect.

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.

Troubleshooting and Debugging

It is one of the laws of computer programming that any non-trivial program will not work the first time you run it. You will need to spend some time debugging your application. Here are some suggestions:

Standalone mode: Once your program compiles, you can run it in standalone mode. You have to ensure that any files used by boinc_resolve_file(), either or output or input, already exist. Then simply run the executable. It will create a file called init_data.xml containing default (simulated) values for information the application ususally obtains from the BOINC Core Client.

Redirect stderr: It is a good idea to redirect stderr output early in your program, so that if anything goes wrong you can get back some kind of output. The example applications do this. You

Microsoft .NET - just say no The Microsoft .NET framework includes a set of classes and libraries which are supposed to make it easier for developers to write applications in any of a variety of languages but have them all execute within the same Common Language Runtime (CLR) environmnet on any Windows machine. The .NET libraries are shipped with Windows XP and can be installed on Windows 2000, but it seems that they cannot be installed on earlier versions of Windows (NT/Me/98/95). [Need to check this.] Thus if you want your applications to run on older versions of Windows you need to make sure that your application does not depend on the .NET framework. The BOINC core client and Manager are build so that they do not depend on .NET and so will run on any version of Windows.

While working on a complicated application I have found that I have sometimes changed a compiler setting without realizing that it has turned on a dependence on .NET. The application would build fine either way, and will run on the machine it was built on (which has .NET) but not on others. A useful trick for avoiding this is to change the Linker configuration under "Input" to tell it to ignore the library mscoree. Then the build will fail if there is a dependence on .NET.

There may be several ways to introduce a .NET dependence, but the one I know clearly does is to have any of your files set with "Compile as Managed" set to "Assembly Support /CLR". You will have to check each file individually as there is no global options or inheritence of this.

BOINC documentation on troubleshooting: These pages on the BOINC web site can be helpful:

Acknowledgments

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), along with Teviet Creighton and David Hammer. 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.


Last modified: 04 September 2011 Copyright © 2011 by Spy Hill Research http://www.spy-hill.net /~myers/help/boinc/boinc-on-windows.html