Yello, World - Building a BOINC application with graphics

SPY HILL Research

Poughkeepsie, New York

Yello, World - Building a BOINC application with graphics

Topics

Graphics Libraries

Getting the code

Windows

Unix

MacOS X

Running it

Release Notes

This is about the simplest program one can write which runs under BOINC and which also produces some form of graphical output. It just turns the screen yellow for the duration of a short workunit. It demonstrates the configuration needed to build BOINC applications which include graphics.
Last modified: 6 October 2011

Yello, World!
This is the absolute simplest application one can write for BOINC which uses graphics. All it does is turn the screen yellow while the computation thread generates random numbers for a short while.
Why do this?
Because getting graphics to work in BOINC is not trivial, so an example can be useful for getting started. This program has all the BOINC graphics callbacks, they just don't do very much. To create your own BOINC graphics you simply need to add more OpenGL to the appropriate routines. More advanced examples which have working OpenGL animated graphics are the cube demo, and the uppercase sample aplication which is distributed with the BOINC source code (see samples/example_app/uc2_graphics.cpp)
The graphics here are simple, but the build process is not, so the real accomplishment is to give you a working build template for BOINC graphics applications for Unix, Windows and MacOS X.
Following the example of the sample applications that came with BOINC, the yello application is not compiled for graphics unless you define the pre-processor symbol BOINC_APP_GRAPHICS. If this is not defined then basically you just get the simpler "hello, world" program. But since this is a test of the graphics and build process you should make sure that symbol is defined.
Graphics Libraries
BOINC uses OpenGL for graphics. OpenGL is now supported by the windowing and graphics systems on all of the platforms on which BOINC runs: Windows, Unix, and MacOS X.
BOINC also uses GLUT, the GL Utilities Toolkit. While running applications which use GLUT may be supported automatically on most computers, building applications which use GLUT may require that you download and install GLUT separately. I have had good success with FreeGLUT, an open source re-implementation of the GLUT library.
You will also need the JPEG libraries. Even though this application does not use bitmapped graphics, the BOINC graphics utilities (gutil.C) include functions that link against various graphics libraries, including the JPEG libraries. See the notes here about building the JPEG libraries on Windows.
Getting the code
You can get a tarball containing the source code and build scripts here.
You can also get the code via CVS. On unix the command is:
% cvs -d :pserver:anonymous@spy-hill.net/usr/local/cvsroot/boinc checkout src/apps/yello.d
Then move the directory yello.d to wherever you want to use it. On Windows you need to put this in the boinc/apps folder.
Since BOINC v6 the screensaver graphics have been moved to a separate program (instead of just a separate thread). The code for the main graphics program is common to all of the example applications and can be downloaded here: graphics_app.C
Windows
You will want to unpack this as the folder boinc/apps/yello.d (i.e. under the BOINC apps folder). If you are checking it out of CVS then this may prove a bit tricky, since it is not stored in CVS under that path. Check it out from CVS to some working directory, and then drag the yello.d folder to boinc/apps/.
I've built and tested this with MS VC++ 2003 and 2008. The "solution" in yello.sln has two "projects", defined by yello.vcproj (for the computation program) and yello_graphics.vcproj for the screensaver graphics. Just build the while "solution", and the executables will both end up in the Build/Debug sub-folder. (Solution and project files for VC++ 2003 have "_2003" in their names.)
See the notes here about building the JPEG libraries on Windows. The project file for yello_graphics looks for the JPEG library in C:\lib and the header file in C:\include\jpeglib; you can change both by changing the Properties of the Project in MSVC++. To do so, right click on the 'yello' project and pull down to the Properties menu item at the bottom. You can change header file locations under "C/C++" and change library locations under "Linker".
See the notes here about building GLUT on Windows. On windows you should build freeglut as as static library, and then build your application with the pre-processor symbol FREEGLUT_STATIC defined (or you'll get screwed by a #pragma which will ask for the dynamic library). The project file looks for the library file freeglut_static.lib in the directory C:\lib, and looks for header files in C:\include\freeglut\GL; you can change both by changing the Properties of the Project in MSVC++. As you'll see in the Preprocessor section of the Properties, the macro FREEGLUT_STATIC is defined.
You need GLUT on Windows even though this application (yello) does not use it, because there are references to it in the BOINC code, and they are not easily untangled. Besides, you will need it for any screensaver more interesting than this.
Unix
Most Unix distributions include the OpenGL headers, and the OpenGL functionality is included in the X11 server software for a particular graphics card. If you have X11 configured correctly, you likely have OpenGL installed and configured correctly. (check that you don't need developer's version...)
You need the JPEG libraries. Again, these are usually a standard part of most Unix distributions, but if you need to or want to build from source then see the notes here.
You still need GLUT. Even though this application does not use any GLUT, the BOINC graphics API uses GLUT to open and control windows and for fonts. You also need GLUT just to build the BOINC libraries. More detailed notes on building and installing GLUT can be found here here. (Right now they are very sparse, but I'm working on a separate web page just about GLUT for BOINC, which I hope will be ready soon.)
You can build yello anywhere, but it's easiest to unpack it as the directory 'yello.d' under the 'apps' directory in the BOINC source tree. The Makefile is set up so that you can build in one of two ways: A) the headers and libraries are obtained from wherever you built BOINC, as pointed to by the BOINC_BUILD variable in the Makefile; or B) the headers and libraries are obtained from where you have installed BOINC on your system, as pointed to by the BOINC_PREFIX variable in the Makefile. You can edit the Makefile to select either option; just be careful not to mix the two or you'll get very confused.
Once you have reviewed the Makefile and set it up for option A or B, just say 'make yello' to build the application.
MacOS X
There are two ways to build applications on MacOS X. Apple provides a graphical Integrated Development Environment (IDE) called XCode for building any kind of application on a Mac. But since MacOS X is based on Unix, the traditional Unix make utility will also work. Still, there are some differences between the Unix on a Mac (Darwin) and other versions of Unix....
Building the application this way is almost the same as on Linux. The instructions are in a slightly altered version of the Makefile. To use it the command (from a shell window, such as with Terminal.app) is:
    make -f Makefile.Mac
On the BOINC web site you will find additional notes on building BOINC clients and applicaation on MacOS X.
Running it
Add the application to the project database as described here.
The script yello.sh will create work for one workunit, using the workunit template file mellow_wu.xml and the result template file yello_re.xml. It is basically a wrapper to run the create_work program to create one workunit. Make sure the template files are in PROJECT/templates. You'll need to edit yello.sh to change the main PROJECT directory to match your installation. Or you can just give the create_work command shown in the script "by hand", since that is all that is really needed to create a workunit.
If you append _nodelete onto the workunit name then that workunit can be used as a seed for generating work using the make_work program, which comes with BOINC, and the files associated with that workunit will not be deleted from the database even after it has been "assimilated".
Release Notes
Here are more specific notes for particular versions of yello as they are released:

yello 6.08 (1 Oct 2011)
No change to the code, just changes to the build process. Built with BOINC trunk version 6.13.1 of 5 Sept 2011. The Windows build configuration was updated to use MS VC++ 2010 Express Edition, which is the current version of the free compiler available from Microsoft. The new Project file is yello.vcxproj (the file extension changed). The application is now built against static BOINC libraries, instead of just selected source code files. The Mac version built by Makefile.Mac is now for Intel Mac rather than PPC. The generic main program for the graphics is now in CVS in ../graphics/
yello 6.07 (11 June 2011)
No change to the code. When building on a machine upgraded from Fedora 10 to Fedora 12 the 'hello' fails to build with the error message
/usr/bin/ld: cannot find -lssl
The problem was that the static version of the OpenSSL library, libssl.a, was not installed, because it was moved to a separate package, called openssl-static. The solution, therefore, is simply to install that package:
# yum install openssl-static
As a general rule, it's good to use static libraries when possible to make the binary more portable. (But you can't do this for graphics libraries, which are different on different machines.)
yello 6.06 (17 September 2010)
Code unchanged. Built with the latest server_stable branch, r22358 (BOINC 6.11.7). For Linux, to build a purely static app on Fedora 12 required that I install the libjpeg-static package, along with freeglut and freeglut-devel. In Fedora 12 only dynamic library versions of freeglut are available as packages, which would result in less portable apps. I therefore built a static version of freeglut from the latest source code. The Makefile has been altered to use the static version of this library.
yello 6.05 (19 September 2009)
Code unchanged, but some adjustments to the Unix Makefile. Built with the server_stable branch, r19110 (labeled version 6.7.0), in celebration of Talk Like A Pirate Day 2009. The windows version was built with MSVC++ 2003 on Windows 2000 (with line 357 of stackwalker_win.cpp removed).
yello 6.04 (7 February 2009)
Built with the SVN trunk, r17125, labeled eversion 6.7.0, in anticipation of making it the newest "server_stable" release. The windows version was built with MSVC++ 2003 on Windows 2000.
yello 6.03 (14 December 2008)
Built with the SVN branch "server_stable" r16543, which was at the time labeled BOINC version 6.3.14. Linux and Mac makefiles adjusted accordingly. Windows version built using MSVC++ 2003. The source code of the application remains the same, but the Windows build configuration files have changed to account for the fact that BOINC source code now uses file extension .cpp rather than the .C extension.
yello 6.01 (7 August 2008)
The application was broken into a separate computing program and graphics program, to use the new BOINC 6 graphics API. Built with BOINC 6.3.6 (r15765).
yello 5.13 (14 January 2008)
No changes to the application code. Built with BOINC 5.10.32 from the 5.10 branch (/branches/boinc_core_release_5_10/, r14462) to test that this branch is still working. We found a bug in api/windows_opengl.C; it was missing
HANDLE graphics_threadh;

yello 5.12 (22 November 2007)
Build with BOINC 5.10 branch (boinc_core_release_5_10), SVN rev 14266. Found a small bug in windows_opengl.C - reported to Rom.
yello 5.11 (15 June 2007)
Windows version built with BOINC r12933.
yello 5.10 (15 June 2007)
Built with BOINC source code revision 12933, which is BOINC 5.10.6. No changes to the application source code. Unfortunately, the Windows version was accidentally built with r12903 (BOINC 5.10.5) and has the zero cpu_time bug.
yello 5.09 (18 April 2007)
Built with boinc_core_release_5_9_3. The windows version required the addition of one header file to the Project. Otherwise, everything built directly. The 32 bit versions are released for 64 bit platforms, and the PPC version for Mac is released for Intel Macs to run in "emulation" mode.
yello 5.08 (17 March 2007)
Built with CVS HEAD from 9 March 2007 (no tag, but the library build reported the version as 5.9.2). Several string functions, including parse_command_line(), have been moved to a new file str_util.C. Some windows-specific files have been put in win_util.C. Those files and their associated headers have been added to the Project. Makefile on Mac modified to be easier to build on Mac.
yello 5.07 (8 December 2006)
This release is primarily for MacOS X. I finally figured ou the (relatively simple) proper incantation to build a BOINC application which has graphics on MacOS X using the standard Unix 'make' system (rather than Apple's XCode GUI). See the file Makefile.Mac for the particulars. You still need to have XCode installed you just don't need to use the GUI.
yello 5.06 (21 November 2006)
No changes to the application code. This version was built with boinc_core_release_5_7_4. On windows we overcame the problem reported in 5.05 by putting some libraries into a list of DLL's for which loading should be delayed.
yello 5.05 (10 November 2006)
No changes to the application code. This version was built with today's latest code (CVS HEAD, no tag), with one small change to comment out some new development code in boinc_graphics_possible() in the file graphics_api.C
yello 5.04 (3 August 2006)
This version was built with BOINC 5.5.4 with explicit static linking go libc++.a, which should make it run correctly on a wider range of Linux variants.
yello 5.03 (6 July 2006)
Updated to build with BOINC 5.5.4, including some file depency changes and simplification of GL headers for Windows. Now does not check return code from initializing diagnostics, since no return code is promised. Graphics API changed "bool" to "int" for better C/C++ compatibility.
yello 5.01-02 (29 January 2006)
Built with BOINC 5.2.15 on Windows (MS VC++ 7.1) and Linux (Fedora Core 3/gcc 3.4.3). Added diagnostic output for stack tracing, but otherwise no major changes.
yello 4.62 (25 May 2005)
Re-compiled with _DEBUG unset after users reported errors on workunits in which they viewed the graphics. Those problems may or may not indicate a problem with the latest BOINC code, so this is is a test. Increased the length of time so that it runs longer than a few seconds on fast machines.
yello 4.60 (24 May 2005)
Re-compiled with latest BOINC code which includes a fix for ATI Radeon 9600 graphics cards. The ATI bug is indeed fixed!
yello 4.59 (22 May 2005)
Increased the amount of work done per iteration so that a workunit does not finish too quickly.
yello 4.58 (20 May 2005)

The code has been simplified considerably by removing the alternative of using the old or new API. Only the new API is now demonstrated.
Trimmed references to GLUT from the MSVC++ project and solution.
Output file name changed to out.txt so that it is easier to read on Windows.
Added simple output to stderr when graphics init and resize routines are called.

yello 4.57 (28 Feb 2005)
Only small changes to the code, but lots more documentation on how to build, including instructions on how to build the JPEG library on Windows.
yello 4.55 (10 Feb 2005)

Code modified to work with both old (pre BOINC 4.52) and new API's.
Makefile introduces separate options to build against BOINC_BUILD (where BOINC was built) or BOINC_PREFIX (where it is installed).
Windows version uses freeglut not GLUT32.

yello 3.20 (20 July 2004)
Original release of the program. Works on Windows with BOINC 3.20.