SPY HILL Research

Poughkeepsie, New York [DIR] [UP]

Hello, BOINC World!

This is about the simplest program you can write for BOINC that does something non-trivial -- the "Hello, World!" program of BOINC. It opens an output file called "out.txt" and writes something to it, and then this file is uploaded to the server when the task completes.

Last modified: 23 December 2014
Getting the code
Building the Application
Testing it
Running it
Release Notes
This is just about the simplest program you can run under BOINC which does something -- the "Hello, World!" program for BOINC.

In the summer of 2004 I worked with one of my students to learn how to write BOINC applications. We did this both by reading the examples which then came with the distribution and by trying to write our own simple programs. As a result, we came up with the simplest BOINC program, the "Hello, World!" program of BOINC. It just opens a file and writes to it, and that file is then uploaded to the server by the BOINC client.

We'd like to share this with anybody who might also have to go through the whole process of learning to write BOINC apps.

Getting the Code and files

By itself, here is the program: hello.C

But to make use of this you will need some instructions for building it (a Makefile for Unix, or "project" and "solution" files for Microsoft Visual C++), along with template files to support running it on a BOINC project. The easiest way to get the code is via CVS. On Unix the command is

$  cvs -d :pserver:anonymous@spy-hill.net/usr/local/cvsroot/boinc checkout src/apps/hello.d
On Windows you fill the same information into the menus of your CVS tool (such as WinCVS, TortoiseCVS). Then move the directory hello.d to wherever you want to use it. On Windows you should move it to the boinc/apps folder to get the paths in the "project" file to match up correctly (or else you can change those paths, which will be more work).

Building the Application

Building a BOINC application is straightforward once you have your system set up for it. See the notes here for your platform.

For Windows you will find in the source folder both "solution" and "project" files for MSV 2003 and 2008. Simply open the "solution" file, right-click on the "hello" solution, and pull down to the "Build" item. You do not need to build BOINC -- the project builds against the BOINC source code, but not any BOINC libraries (this is different from how the examples distributed with BOINC are built, and how more complex applications should be built). After the program is compiled you will find the executable in the Build/Debug/ sub-folder.

For Linux there is a Makefile. It is set up to build the application using either BOINC where you built it, or where you installed it (see the comments in the Makefile for further instructions). For Linux you should build the BOINC libraries first.

For Darwin (the Unix on Apple computers) there is currently a separate makefile called Makefile.Mac. It is quite similar to the Linux Makefile. To use it, give the command

  make -f Makefile.Mac
See the comments in the file for further details. I do not (as of yet) have an XCode project file for this app, so the only way to build the application is via the Makefile. At some point if there is interest I will also create an Xcode project file.


You can run this program in
"standalone" mode to test it without having to go through all the steps of adding it to your BOINC project and running it that way. On windows the executable will be in the Build/Debug subfolder. A file called out.txt must exist in the same directory as the executable before you run the program. (If it does not, a message saying "cannot resolve output filename" will appear in an output file called stderr.txt.) Then simply run it as a program. On Windows double-click on the executable. On Unix (including Darwin) just say `./hello` and wait for it to finish.

If the program runs succesfully then you will find some output in out.txt and in a new file named stderr.txt. There will also be an empty file named boinc_finish_called, and a file called init_data.xml, containing default values for user and host information, which is created the first time the application is run in standalone mode.

On Unix you can run the program and get timing information with the Unix time command, like this:

   time hello
This can give you an estimate of how long the program will take to execute on your BOINC project. For comparision, on an 860MHz Pentium III running Linux it took about a minute, but on a 233MHz AMD K6-2 it took nearly five minutes. Obviously it will run faster on newer computers.

Running it with BOINC

See "
Adding and Updating BOINC applications" for detailed instructions on how to add an application to your BOINC project. (These instructions are also included in the 'hello' tarball as the file app_add.html.) Basically, you first need to "add" the application to your project (i.e. add it to the database) and then "release" a new version of the application by copying the executable to the PROJECT/apps/hello directory and running the update_versions script.

Make sure the template files are in PROJECT/templates. You need both the Workunit template file world_wu.xml and the Result template file hello_re.xml.

The script hello.sh will create work for one workunit, using the template files mentioned above. It's just a wrapper which invokes the create_work command to create one Workunit. The script will use the environment variable BOINC_PROJECT to find your project directory, or you can edit the file directly to match your own installation.

If the program runs succesfully you should find a copy of the out.txt file returned to the PROJECT/upload directory (it will have a different name), and you should be able to read the stderr output by looking at the workunit/result for the Result from the web via the project operations pages. You will want to do your first test with the file_deleter daemon stopped, or else it will likely delete the copy of the out.txt file before you can read it.

A succesful Result will yield a credit reward of a few hundredths of a cobblestone (a few cobble-cents? :-). It's not very much, but it is enough to show that your project is working correctly. Congratulations!

Release Notes

The 'hello' application is also used to test new BOINC software as it is developed. Here are more specific notes for particular versions of hello as they have been released:
hello 6.12   (19 September 2011)
No change to the code. 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 hello.vcxproj (the file extension changed). Also added some new source files to the Project, specifically procinfo.cpp, url.cpp, coproc.cpp, and procinfo_win.cpp and associated .h header files.
hello 6.11   (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 -lm
The problem was that the static version of the math library, libm.a, was not installed, because it was moved to a separate package, called glibc-static. The solution, therefore, is simply to install that package:
# yum install glibc-static
hello 6.10   (24 September 2010)
Building BOINC on the Mac now builds both static and dynamic libraries. When linking the executable for this application it links against the dynamic version of the libraries if they are found. To prevent that, making the app more portable, I simply deleted the dynamic versions of the libraries before linking the application executable.
hello 6.09   (19 September 2010)
The Mac version failed miserably because it was looking for dynamic libraries which were missing on most if not all hosts. In this version we packaged up the dynamic libraries with the executable, but that still failed.
hello 6.08   (19 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 glibc-static package. It seems that libm.a has been moved to this separate package, and glibc-devel only has the dynamic library libm.so.
  • For Windows, using MS VC++ 2003, I again had to modify stackwalker_win.cpp (this time line 363, which uses Module.CVData, which is not defined), and define vsnprintf to be _vsnprinf. I also added two new files to the Solution for this app, url.cpp and coproc.cpp (and their headers).
  • For MacOS X, the program compiled but failed to run, complaining of a missing symbol: kCFAllocatorDefault. The solution was to add `-framework Cocoa` to the link step.
hello 6.07   (26 November 2009)
Code unchanged. Built with the latest server_stable branch, r19508 of Friday, 06 Nov 2009. To build the Windows version with MSVC++ 2003, which uses the .NET/1.1 Framework I added to the file boinc_win.h the line
#define vsnprintf _vsnprintf
I put this in a block which according to the comments would only be used for MSVC versions prior to the 2005 edition.
hello 6.06   (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).
hello 6.05   (4 February 2009)
Built with the SVN trunk, r17125 (labeled version 6.7.0), in anticipation of making that the newest "server_stable" release. The windows version was built with MSVC++ 2008 on Windows XP. Building with MSVC++ 2003 on Windows 2000 also worked (but see note below about stackwalker.cpp)
hello 6.04   (9 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.
hello 6.03   (19 September 2008)
Same code as hello 6.02, but built for Apple Mac OS X.

hello 6.02   (18 September 2008)
Adjusted to account for fact that with BOINC 6 you no longer need to define graphics entry points, even if there are no graphics. The problem with md5_file.C on Windows was cleared up by turning off pre-compiled headers. Line 357 of lib/stackwalker_win.cpp had to be commented out to compile, due to an undefined symbol.

Built with BOINC 6.3.10 (r16023). MSVC++ 2003 solution and project files now become new files with "_2003" appended, as I now also create versions for VC++ 2008.

hello 6.01   (1 August 2008)
No changes to the application code. Built with BOINC 6.3.6 (r15739). Found two small problems on Windows: 1) undefined variable Module.CVData in file stackwalker_win.cpp, and 2) strange problem with file md5_file.C triggering an error saying that config.h could not be included, even though it is not supposed to be included. Fixed either by a) turning off automatic precompiled headers for that one file, or b) by re-ordering the test for _WIN32. Very odd.
hello 5.16   (11 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. It is.
hello 5.15   (21 November 2007)
No changes to the application code. Built with BOINC 5.10.30 (/branches/boinc_core_release_5_10/, SVN rev 14266) to test that this branch is still working.
hello 5.14   (21 November 2007)
No changes to the application code, other than to comments. Built with BOINC 6.1.0 SVN head (r14266) just to verify that the newest version of the BOINC code is working.
hello 5.13   (14 June 2007)
No changes to the application code. Built with r12933, with a change to BOINC software which should fix the bug just found.
hello 5.12   (12 June 2007)
No changes to the application code. Built with BOINC version 5.10.5 (Subversion revision 12903), which works for Windows, Linux, and Mac. This run found a bug in the BOINC code which caused the CPU time of a Workunit to be reported as 0.00, and hence also a claimed credit of zero. Testing is good.
hello 5.11   (11 April 2007)
No changes to the application code. Built with boinc_core_release_5_9_3. The 32-bit applications for Linux and Windows are now made available for 64-bit clients. The PowerPC Mac version is made available for Intel Mac clients to run in "emulation" mode.
hello 5.10   (9 March 2007)
Built with today's latest code (CVS HEAD, no tag, but the server code reports 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 their associated headers have been added to the Project.
hello 5.09   (8 November 2006)
No changes to the application code. Built with today's latest code (CVS HEAD, no tag). The problem reported with hello 5.08 is not present.
hello 5.08   (30 October 2006)
No changes to the application code. Built with boinc_core_release_5_5_16 to test the BOINC code base. And we found that it does not work correctly with that version of the BOINC code, because the app cannot parse the init data file, and therefore runs in standalone mode.
hello 5.07   (15 June 2006)
The graphics API changed some arguments from bool to int for C/C++ compatibility. Even though this app has no graphics it does have dummy functions which need to be changed. It was compiled using boinc_core_release_5_5_4. The Mac version was built on Tiger and seems to fail on Panther boxes.
hello 5.06   (27 May 2006)
Recompiled on Linux on Fedora Core 4 (gcc 4.0.2) after building BOINC on the same machine with code updated from CVS from date 7-May-2006, and the standalone version runs correctly without SIGSEGV.
hello 5.05   (17 May 2006)
As of BOINC 5.4 the diagnostics initialization routine boinc_init_diagnostic() returns a non-zero value even under some non-error conditions, such as when it cannot find the file init_data.xml (which it therefore just creates). The hello.C program was therefore modified to not exit if this routine returns a non-zero value. This is the more correct behaviour anyway, because there is nothing in the documentation that says a non-zero return value indicates an error.

The Linux version was built as a static executable on Fedora Core 3, using the CVS HEAD version of BOINC (version 5.4.9). It runs correctly in standalone mode on Fedora Core 3. When built and run on Fedora Core 4 the program runs correctly but then terminates with a SIGSEGV and a two item stack trace. The version built on FC3 runs correctly with no errors on FC4 (as you would expect for a static binary), so it appears to be an issue with the build environment, possibly the compiler (gcc 4.0.2). We will investigate this further.

hello 5.04   (27 Feb 2006)
This version of the application used the same code as hello 5.03, but was compiled on Windows using the build configuration used by the sample programs distributed with BOINC. It failed miserably when released to Pirates@Home, because it needed libraries which are not included on every Windows machine, causing the app (and BOINC itself) to stop with an error messsage box. This version of the app was therefore quickly deprecated, and best forgotten.
hello 5.03   (18 Feb 2006)
Compiled with BOINC 5.3.19 on Unix. Works fine when compiled with gcc 3.4.4 (as on Fedora Core 3), but the static binary ends with SIGSEGV when compiled with gcc 4.0.2 (as on Fedora Core 4). Required BOINC 5.3.18 (not 19) on Mac.
hello 5.01   (14 Jan 2006)
Compiled with BOINC 5.2.15 on Windows (no changes required) and on Linux (now requires -pthread flag for loading).
hello 4.61   (11 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.
hello 4.58   (8 May 2005)
I changed the name of the output file to out.txt so that it is easier to read on Windows.
hello 4.54   (11 Nov 2004)
I added an example of how to use the BOINC diagnostics API, so that you can write to stderr and get the output back. So in some sense this is no longer the absolute simplest BOINC program you can write, but I felt that being able to use stderr was so important that I wanted to include it in this simplest example program.
hello 4.03   (15 Sept 2004)
Updated and tested with BOINC 4.0 (no major changes).
hello 3.13   (9 July 2004)
Initial release of the program.

Additional notes

You don't actually need check out the whole directory from CVS to get started. You can just put the code in the file hello.C in the apps directory, and then edit the Makefile to change "1sec" to "hello" everywhere and it will build.

But you will want the templates and other files in the CVS directory to get the application to run on your BOINC project.

I'd like to suggest to the BOINC developers that they make this change in their distribution of BOINC: Replace 1sec with hello. The 1sec app does not work (when run under BOINC). When we first started learning BOINC we were distracted into trying to get it to run, until we figured out that it does not use the proper API. I see 1sec is mainly used for the test suite, so if it is to be kept then maybe move it to the test/ directory.
  Copyright © 2014 by Spy Hill Research https://www.spy-hill.net/help/boinc/hello.html (served by Islay.spy-hill.com) Last modified: 23 December 2014