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.
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.
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
|
http://www.Spy-Hill.net/help/boinc/hello.html
|
(served by Islay.spy-hill.com)
|
Last modified:
23 December 2014
|
SPY
HILL
Research