= Single-job submission: implementation notes =

BOINC's [SingleJob single-job submission system]
is a streamlined way to run a single job remotely.
It's implemented by:

 * '''html/ops/single_job_setup''', a script which configures a project to handle single-job submission;
 * [SingleJob tools/boinc_submit], which submits a job.
 * single_job_assimilator, an assimilator for single jobs.

The mechanism is implemented as follows:

 * Single jobs for a given platform use the application '''single_job_PLATFORM'''.
 * App versions for this app run the [WrapperApp wrapper] program.

'''single_job_setup''' does the following:

 * Check that the wrapper has been compiled (i.e. boinc/samples/wrapper/wrapper exists).
 * Add the application '''single_job_PLATFORM''' to the DB if needed.
 * Create a project/apps/single_job_PLATFORM directory if needed.
 * Scan through the subdirectories of this, looking for the highest version number.
 * If there are no subdirectories, or if the application in the highest-version subdirectory isn't current, create a new subdirectory and copy the wrapper app to it.
 * Print instructions for running update_versions if needed, and/or adding <daemon> entries to config file.

NOTE: '''single_job_setup''' is hardwired with the '''i686-pc-linux-gnu''' platform
(i.e. Linux on Intel32).
If you want to use other platforms, edit the script.

'''boinc_submit''' does the following:

 * Check that the project has been configured to do single jobs for the given platform.
 * Create a WU record for the job.
 * Make a job.xml file for this job.  This has the physical name '''sj_WUID.xml''', where WUID is the ID of the workunit.
 * Make a "job directory file", sj_WUID, in the upload directory hierarchy.  This contains the directory from which boinc_submit was run, so that the assimilator can put output files there.
 * Create WU and result template files (sj_wu_template_WUID and sj_result_template_WUID).  The input files include the job.xml file and the program executable.  The executable is declared as sticky.  Its name (logical and physical) is '''program_PLATFORM_CKSUM''', where CKSUM is the first 8 characters of the file's MD5.
 * Copy input files and the executable to the download hierarchy.  The physical name of input files is '''name_WUID'''.
 * Invoke [WorkGeneration#creatework-tool create_work] to finish creating the job.  Pass a --wu_id flag to tell create_work not to create a new workunit.

'''single_job_assimilator''' does the following:

 * Read the job directory file.
 * For each output file, look up its logical name in the result's xml_doc_in.  Then copy the output file to the job directory, using the logical name.