[Debian Wiki] Update of "BOINC/ServerGuide/WrapperApp" by dhananjay

[Debian Wiki]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Debian Wiki" for change notification.

The "BOINC/ServerGuide/WrapperApp" page has been changed by dhananjay:
http://wiki.debian.org/BOINC/ServerGuide/WrapperApp

Comment:
Created the page.

New page:
#language en
#pragma section-numbers 1
#pragma keywords BOINC, Grid Computing, Volunteer Computing, Open Source, Debian
#pragma description Tutorial for preparing a Debian-based server instance for a BOINC project - subsection on wrapper application deployment.

<<TableOfContents(2)>>

''' This page is about deploying a wrapper application with BOINC on Debian or Ubuntu. It extends the page [[BOINC/AppDeployment]] page.'''

= Wrapper Application =

BOINC provides a wrapper app to use normal binaries in a BOINC environment. The sources are shipped with BOINC, and is available in debian through boinc-app-examples package.

In short, The wrapper system works like this, 
 * BOINC executes the wrapper binary, which BOINC considers as a multi-file application.
 * wrapper checks the execution folder for a job description file, named job.xml, and parses it to get the actual binary names.
 * wrapper calls the actual binary, checks its progress through check point files if defined.
 * After the payload has completed execution, wrapper calls boinc_finish and exits itself.
 * The BOINC client uploads the results back.

== Deployment ==

'' In the experiment branch, Multifile project management of BOINC has changed a lot. Please note that the steps illustrated here are for the debian boinc-server-maker package or more specifically, [[ http://boinc.berkeley.edu/svn/branches/server_stable | sever_stable]] branch of BOINC. ''

The deployment is little bit tricky, as of now, cant just apt-get them. (well, we are working on it.).

The wrapper deployment is explained here as cases, select one with your requirements and follow. The documents here are a follow up from AppDeployment page. It assumes that you are familiar with the normal app deployment using debian and BOINC.

=== Obtain the binaries ===

Use the fetch_example_applications script provided with the boinc-server-maker package to obtain the binaries for the wrapper applications, copy them to the app folder of the project root. Since this is a multifile project, the directory hirearchies are important. The binaries should be arranged as follwing structure.

In multi file applications, The files are put in a subdirectory of name appname_version_fullplatformname.

{{{
apps/
`-- wrapper
    |-- wrapper_6.12_i686-pc-linux-gnu
    |   |-- wrapper_6.12_i686-pc-linux-gnu
    |   `-- wrapper_6.12_i686-pc-linux-gnu.sig
    |-- wrapper_6.12_ia64-linux-gnu
    |   |-- wrapper_6.12_ia64-linux-gnu
    |   `-- wrapper_6.12_ia64-linux-gnu.sig
    |-- wrapper_6.12_mips-linux-gnu
    |   |-- wrapper_6.12_mips-linux-gnu
    |   `-- wrapper_6.12_mips-linux-gnu.sig
    `-- wrapper_6.12_x86-64-pc-linux-gnu
        |-- wrapper_6.12_x86_64-pc-linux-gnu
        `-- wrapper_6.12_x86_64-pc-linux-gnu.sig
}}}



=== Configuring the wrapper ===
The wrapper binary on running checks for a job description file named ''job.xml'', which is used to inform the wrapper about the actual bianry and the arguments to pass. This file has to be present in project root.

Sample job.xml
{{{
<job_desc>
    <task>
        <application>binary_name_to_call</application>
        <command_line>arguments_to_pass</command_line>
	<stdin_filename>stdin_file</stdin_filename>
        <stdout_filename>stdout_file</stdout_filename>
        <stderr_filename>stderr_file</stderr_filename> 
    </task>
</job_desc>
}}}



== Simple script with no input ==
The example script used in this section counts from 0 to a number specified as command line argument, and outputs as ''out''.

{{{
user at host $ cat count 
#!/bin/bash
seq $1
}}}

=== Create directory structures ===
The job description file for this script will look like this,

{{{
<job_desc>
    <task>
        <application>count</application>
        <command_line>1000</command_line>
    </task>
</job_desc>
}}}

As mentioned the payload binary/script has to be copied to the subdirectory for each platform. Since the script doesnt have any platform dependencies, we do

{{{
user at host $cd $projectroot
user at host $for p in apps/wrapper/*/
do
cp path/to/count path/to/count.sig path/to/job.xml path/to/job.xml.sig $p
done
}}} 

Now the app directory should be
{{{
apps/
`-- wrapper
    |-- wrapper_6.12_i686-pc-linux-gnu
    |   |-- count
    |   |-- count.sig
    |   |-- job.xml
    |   |-- wrapper_6.12_i686-pc-linux-gnu
    |   `-- wrapper_6.12_i686-pc-linux-gnu.sig
    |-- wrapper_6.12_ia64-linux-gnu
    |   |-- count
    |   |-- count.sig
    |   |-- wrapper_6.12_ia64-linux-gnu
    |   `-- wrapper_6.12_ia64-linux-gnu.sig
    |-- wrapper_6.12_mips-linux-gnu
    |   |-- count
    |   |-- count.sig
    |   |-- wrapper_6.12_mips-linux-gnu
    |   `-- wrapper_6.12_mips-linux-gnu.sig
    `-- wrapper_6.12_x86-64-pc-linux-gnu
        |-- count
        |-- count.sig
        |-- wrapper_6.12_x86_64-pc-linux-gnu
        `-- wrapper_6.12_x86_64-pc-linux-gnu.sig

}}}

Use xadd and update_versions to put the app to database.

The executable permission for the script should be set.

=== Workunit ===
The application doesnt have an input, and do a trivial small computaion. A sample workunit template for the script should look like

{{{
<workunit>
    <rsc_fpops_bound>1e12</rsc_fpops_bound>
    <rsc_fpops_est>1e14</rsc_fpops_est>
</workunit>
}}}

rsc_fpop directives are used to define computaional size parameters, expressed as number of FLOPS needed by the program.

The count produces a file named ''out'' as output, which should be transported back, the result template will be
{{{
<file_info>
    <name><OUTFILE_0/></name>
    <generated_locally/>
    <upload_when_present/>
    <max_nbytes>5000000</max_nbytes>
    <url><UPLOAD_URL/></url>
</file_info>
<result>
    <file_ref>
        <file_name><OUTFILE_0/></file_name>
        <open_name>out</open_name>
        <copy_file/>
    </file_ref>
</result>
}}}

Finally create work, 
{{{
user at host $cd $projectroot
user at host $./bin/create_work --appname wrapper --wu_name wrapper_test --wu_template /path/to/wu/template --result_template /path/to/result/template
}}}