SPY
HILL
Research
|
SPY
HILL
Research
|
Spy-Hill.net
|
| Poughkeepsie, New York | [DIR] [UP] |
Hello, BOINC World!
Here 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 this file is uploaded to the server when the task completes.
Last modified: 11 January 2008 This is just about the simplest program you can run under BOINC which does something -- the "Hello, World!" program for BOINC.
Topics Getting the code Building the Application Testing it Running it Release Notes 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.CBut 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.dOn 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
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.make -f Makefile.MacTesting
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 helloThis 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.
http:// www.spy-hill.net /~myers/help/boinc/hello.html Last modified: 11 January 2008