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 MS
Visual C++ 7), and 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).
You can also get the code and files as a "tarball" named hello-5.xx.tgz in
this directory
(where "xx" is the latest version number).
It unpacks into a subdirectory called hello.d, which you can
put in boinc/apps (or wherever else you want, at least on Unix).
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 MSVC++7.
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, 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.
If you are using a different version of MSVC++ or a different tool you
may still find the settings in the project file useful, if somewhat
hard to get at without MSVC++7.
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 the Mac) 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 one.
Testing
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.
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 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 may want to do your first test with the file_deleter daemon
stopped or it may delete the copy of the out.txt file.
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.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 the tarball 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 tarball 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.
Please send corrections or suggestions for improvement to
myers@spy-hill.net
|
http://
pirates.spy-hill.net
/help/hello.html
|
Last modified:
18 September 2008
|
