SPY HILL Research

Spy-Hill.net

---

Poughkeepsie, New York [DIR] [UP]

---

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

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:

• Compiler: Microsoft Virtual C++
• Source code via CVS
• Graphics Libraries including: OpenGL and GLUT JPEG library, image libraries, wxWidgets (only for BOINC Manager)
• Demonstration Programs
• Acknowledgments

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

• Creating BOINC projects
• Development and Debugging
• Compiling BOINC Software

• The Unofficial BOINC Wiki (in English)
• Deutsche BOINC FAQ (auf Deutsch)

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:

• It must compile BOINC .C files using C++. To do this go to the project "Properties", and see C/C++ -> Advanced -> Compile As.

  If your application uses C code (.c files not .C or .cpp files) then you can set the properties of individual files to compiles as C code rather than C++.

• 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

MS Visual C++ "Express"

http://lab.msdn.microsoft.com/express/visualc/usingpsdk/default.aspx

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

Cygwin

Bloodshed

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 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:

• GLUT 3.7 beta from OpenGL.org
• GLUT 3.7.6 from Nate Robbins
• freeglut, an open source alternative to the original GLUT implementation

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

• Get the source code from http://freeglut.sourceforge.net/
• Build the static version of the library - many BOINC client hosts don't have a .DLL for it
• Put the header files where they can be used to compile the application.
• Compile your application with FREEGLUT_STATIC defined.

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:

• Under "C/C++" locate the item "Additional Include Directories" and add to this list C:\include\jpeglib or wherever you put the JPEG header files.

• Under "Linker" locate the "Additional Library Directories" and add to this the directory C:\lib or wherever you put the JPEG library file.

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.

• the Hello World program for BOINC
• concat (comes with the BOINC distribution) - demonstrates file input and file output
• the simplest graphics program - yello, World!
• uppercase (comes with the BOINC distribution)
• LaLanne - exercise the full BOINC API
• scroll - scrolling text demo of graphics and of handeling input files
• sextant - the Einstein@Home screensaver
• starboard - xscreensaver GL graphics suite

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

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:

• The BOINC Diagnostics API
• Application debugging on Windows