This page explains how to configure the BOINC server side to support and distribute a particular set of applications to its volunteers.

= How to add a scientific application to a BOINC server =

The BOINC project managers need to provide all the binaries for all the supported platforms. This is of some difficulty especially for those platforms that one does not own oneself. This page's first half demonstrates the workflow using xadd for a single platform, i.e. the one we can work with locally. The second half of this page is dedicated to employing the binaries Debian provides for the purpose. Debian supports many platforms, and we just reply on Debian's infrastructure to have built those correctly without our intervention.

With BOINC's wrapper application, every regular command line execution can be run by BOINC. One just needs to distribute the wrapper together with the application. A separate [[BOINC/ServerGuide/WrapperApp|page]] describes how to substitute the BOINC-prepared example application described here with a triplet of the BOINC-prepared Wrapper application, a description on the invocation and the binary to run. And again, while input data and the invocation are platform agnostic, the platform-dependent applications and specialised libraries can be taken from Debian. This holds for all BOINC projects, not just for those that use the Debian boinc-server-maker package to get started.

== Add a single example app for a single architecture to the BOINC project ==

The process is as follows. Within the project folder we have all binaries for all platforms for a particular application together. What we have we write into a file named "project.xml". Once done, we invoke the tool "xadd" from the project's bin folder. Once done, the BOINC server is ready to accept workunits for that application.

The example application used in the document is ''upper_case'', which converts text inside a file to all capitals. To verify that the package just installed truly shows that binary, it may just have been renamed, use regular Debian command line tools: {{{$ dpkg -L boinc-app-examples | grep upper_case/usr/lib/boinc-server/apps/upper_case}}}

=== Create a directory and add the app to project configuration. ===

This directory becomes an intrinsic part of your project. It needs to reside in a subdirectory of what is accessible through your project's website. After all, it is that website that is contacted by the BOINC clients.

We now copy the file from the above installed "boinc-app-examples" Debian package into that directory and rename it to distinguish versions and architectures. The naming obeys a particular theme that BOINC expects. In our case, the ''app_ver'' variable is that of the BOINC server, the second part of the filename is that of the BOINC architecture. The code below executes the tool 'arch' of the coreutils package to learn about the UNIX platform. The BOINC platforms commonly directly derive from them. The $( .. ) is equivalent to the backticks {{{` `}}} that may be more familiar. And when substituting a variable within a larger string, the variable name is enclosed in curly brackets ${...} .

{{{appver=7.042 # adjust to the right version, only have single "."boincplat=$(arch)-pc-linux-gnu # adjust to your architecture, maybe i686-pc-linux-gnubinary=$(dpkg -L boinc-app-examples | grep upper_case)echo "I: Application version: $appver"echo "I: BOINC platform: $boincplat"echo "I: binary at: $binary"if test -z "$appdir" -o -z "$appver" -o -z "$boincplat" -o -z "$binary"; then echo "E: Lost onee of the variables appdir, appver, binary or boincplat - please check and try again"else completepath=$appdir/$appver/$boincplat && \ sudo mkdir -p $completepath && \ sudo cp $binary $completepath/upper_case_${appver}_${boincplat} && \ echo "[ok]"fi}}}Upstream lists official BOINC architectures [[http://boinc.berkeley.edu/trac/wiki/BoincPlatforms|here]]. The hierarchy of directories looks like an overkill at a first sight. But over time, BOINC projects have become increasingly complex and more often than not, one wants to add more than a single binary. And that team of binaries and data files may have version dependencies among themselves.

The official description of that format is on the BOINC wiki for [[http://boinc.berkeley.edu/trac/wiki/AppVersionNew|AppVersionNew]] - just slighty hidden.

== Optional and outdated: Use the Debian-provided script to install binaries for multiple platforms ==

''Some volunteer please bring the script up to speed for the new hieararchical directory structure as explained above. Until that is done, please bear with us and prepare those platform directories manually.''

When applications do not have dependencies on non-standard dynamically loaded libraries (test with the tool 'ldd'), then one can use the regular binary from Debian. This should then be functional also for non-Debian/Ubuntu platforms. The boinc-server-maker package provides a shell script that downloads the Debian packages of a given name (the default is the boinc-app-examples package) and unpacks, organizes and signs the binaries readily to be redistributed by the BOINC server.

The application will now be downloaded, and the directory structure will look somewhat like this. The .sig files may already have been added by the ''fetch_example_applications.sh'' tool, if your environment variables suggest an active project. But that is optional.{{{$ tree ~/fetch-app/apps

The project.xml file informs the BOINC server about what this project is all about, i.e. what platforms we are supporting with what tools (''apps''). You can copy and paste the following BASH shell lines to your local console. It will create the file ''project.xml'' in the project's root directory or bail out if something goes the unexpected way.

This file feed the xadd tool, which in turn feeds the project's MySQL database. The entries say that those applications should be prepared for to be eventually found. Thus, it is OK if only one of the 32 and 64 bit platforms are covered. Please look into standard platform names BOINC follows [[http://boinc.berkeley.edu/trac/wiki/BoincPlatforms|here]] to avoid confusion.

Now let us invoke xadd. Change to the '''$projectroot''' {{{cd "$installroot"/"$projectname"}}}and run initiate the addition of the binary found in the directory structure to the local database {{{sudo bin/xadd}}}

This is the output of xadd parsing two platform specifications and a single application. More platforms with more applications make longer outputs. Also it should be noted that currently xadd has no provision to delete from databases. It always appends the entries to database, if you want to remove/change existing entries, you should do it manually. Please indicate any better solution or send us emails.

BOINC signs the application binaries for security reasons. This way, the volunteer's client may rest somewhat assured that the application's binary was not modified by someone with evil intentions, say, on the way from the project's server to the local machine.

It should be noted that the app directory is just a staging area for the script to parse the structure and put the binaries to respective places, i.e. the "download" directory. After this, the app directory can be removed safely.

When you have the leisure, don't shy away from inspecting the database more. Except for ''app'', ''app_version'' and ''platform'', all tables are empty at this stage. Straight forward to learn, a very basic tutorial on MySQL will do as a preparation ... if required at all.

This page explains how to configure the BOINC server side to support and distribute a particular set of applications to its volunteers.

1. How to add a scientific application to a BOINC server

The BOINC project managers need to provide all the binaries for all the supported platforms. This is of some difficulty especially for those platforms that one does not own oneself. This page's first half demonstrates the workflow using xadd for a single platform, i.e. the one we can work with locally. The second half of this page is dedicated to employing the binaries Debian provides for the purpose. Debian supports many platforms, and we just reply on Debian's infrastructure to have built those correctly without our intervention.

With BOINC's wrapper application, every regular command line execution can be run by BOINC. One just needs to distribute the wrapper together with the application. A separate page describes how to substitute the BOINC-prepared example application described here with a triplet of the BOINC-prepared Wrapper application, a description on the invocation and the binary to run. And again, while input data and the invocation are platform agnostic, the platform-dependent applications and specialised libraries can be taken from Debian. This holds for all BOINC projects, not just for those that use the Debian boinc-server-maker package to get started.

1.1. Add a single example app for a single architecture to the BOINC project

The process is as follows. Within the project folder we have all binaries for all platforms for a particular application together. What we have we write into a file named "project.xml". Once done, we invoke the tool "xadd" from the project's bin folder. Once done, the BOINC server is ready to accept workunits for that application.

1.1.1. Get binary of local platform

The example application used in the document is upper_case, which converts text inside a file to all capitals. To verify that the package just installed truly shows that binary, it may just have been renamed, use regular Debian command line tools:

1.1.2. Create a directory and add the app to project configuration.

This directory becomes an intrinsic part of your project. It needs to reside in a subdirectory of what is accessible through your project's website. After all, it is that website that is contacted by the BOINC clients.

We now copy the file from the above installed "boinc-app-examples" Debian package into that directory and rename it to distinguish versions and architectures. The naming obeys a particular theme that BOINC expects. In our case, the app_ver variable is that of the BOINC server, the second part of the filename is that of the BOINC architecture. The code below executes the tool 'arch' of the coreutils package to learn about the UNIX platform. The BOINC platforms commonly directly derive from them. The $( .. ) is equivalent to the backticks ` ` that may be more familiar. And when substituting a variable within a larger string, the variable name is enclosed in curly brackets ${...} .

Upstream lists official BOINC architectures here. The hierarchy of directories looks like an overkill at a first sight. But over time, BOINC projects have become increasingly complex and more often than not, one wants to add more than a single binary. And that team of binaries and data files may have version dependencies among themselves.

The official description of that format is on the BOINC wiki for AppVersionNew - just slighty hidden.

1.2. Optional and outdated: Use the Debian-provided script to install binaries for multiple platforms

Some volunteer please bring the script up to speed for the new hieararchical directory structure as explained above. Until that is done, please bear with us and prepare those platform directories manually.

When applications do not have dependencies on non-standard dynamically loaded libraries (test with the tool 'ldd'), then one can use the regular binary from Debian. This should then be functional also for non-Debian/Ubuntu platforms. The boinc-server-maker package provides a shell script that downloads the Debian packages of a given name (the default is the boinc-app-examples package) and unpacks, organizes and signs the binaries readily to be redistributed by the BOINC server.

Obtain the script from /usr/share/doc/boinc-server-maker/examples/fetch_example_applications.sh

The application will now be downloaded, and the directory structure will look somewhat like this. The .sig files may already have been added by the fetch_example_applications.sh tool, if your environment variables suggest an active project. But that is optional.

The boinc_test.conf sets the variables $installroot etc. Start at BOINC/ServerGuide if your search engine had brought you here directly.

2. Inform local database of available binaries

2.1. Craft the project's project.xml file

The project.xml file informs the BOINC server about what this project is all about, i.e. what platforms we are supporting with what tools (apps). You can copy and paste the following BASH shell lines to your local console. It will create the file project.xml in the project's root directory or bail out if something goes the unexpected way.

This file feed the xadd tool, which in turn feeds the project's MySQL database. The entries say that those applications should be prepared for to be eventually found. Thus, it is OK if only one of the 32 and 64 bit platforms are covered. Please look into standard platform names BOINC follows here to avoid confusion.

Now let us invoke xadd. Change to the $projectroot

cd "$installroot"/"$projectname"

and run initiate the addition of the binary found in the directory structure to the local database

This is the output of xadd parsing two platform specifications and a single application. More platforms with more applications make longer outputs. Also it should be noted that currently xadd has no provision to delete from databases. It always appends the entries to database, if you want to remove/change existing entries, you should do it manually. Please indicate any better solution or send us emails.

And when executing that line again, nothing happens since everything here is already inside database, :

2.2. Sign the application binary

BOINC signs the application binaries for security reasons. This way, the volunteer's client may rest somewhat assured that the application's binary was not modified by someone with evil intentions, say, on the way from the project's server to the local machine.

It should be noted that the app directory is just a staging area for the script to parse the structure and put the binaries to respective places, i.e. the "download" directory. After this, the app directory can be removed safely.

When you have the leisure, don't shy away from inspecting the database more. Except for app, app_version and platform, all tables are empty at this stage. Straight forward to learn, a very basic tutorial on MySQL will do as a preparation ... if required at all.