[[PageOutline]]
= Creating application versions =

To create a new applications version:

 * Generate [CodeSigning signature files] for the version's files.
 * Create the directory structure described below
   to store applications files, and place files and signatures there.
 * From the project's root directory, run '''./bin/update_versions'''.
   This copies files to the download directory hierarchy,
   and creates database records for new app versions.
 * Restart the project.

== Application directory hierarchy ==

Store application version files in a directory hierarchy
under '''apps/''' in the project root directory.
The hierarchy has the following structure:

{{{
apps/
  appname1/
    1.0/
      windows_intelx86/
        (files)
      windows_intelx86__cuda/
        (files)
      i686-apple-darwin/
        (files)
      ... other platforms
    1.1/
    ... other versions
  appname2/
  ... other apps
}}}

Each directory under '''apps''' is the short name of an application.

The directories under these are version numbers.
They may be either single integers,
or have the form MAJOR.MINOR, with MINOR < 100.

The directories within a version correspond to application versions.
Their names have the form PLATFORM or PLATFORM!__PLANCLASS
(note that two underscores separate PLATFORM and PLAN_CLASS).
See BoincPlatforms for standardized platform names.
The contents of a particular directory are:

 * Application files
 * Signature files (FILENAME.sig) (see [CodeSigning])
 * A "version description file", '''version.xml'''

== The version description file ==

The structure of '''version.xml''' is:

{{{
<version>
  <file>
    <physical_name>PNAME</physical_name>
    [ <main_program/> ]
    [ <copy_file/> ]
    [ <logical_name>LNAME</logical_name> ]
    [ <gzip/> ]
    [ <url>URL0</url> ]
    [ <url>URLn</url> ]
  </file>
  ... more <file>s

  [<dont_throttle/>]
  [<file_prefix>X</file_prefix>]
  [<needs_network/>]
  [<is_wrapper/>]
  [<beta/>]
  [<api_version>7.4.0</api_version>]
</version>
}}}

File attributes include:

 * '''physical_name''': the name of the file on disk.
 * '''main_program''': designates the main program.
 * '''copy_file''': the file is to be copied into the runtime directory
  on the client, rather than being linked to.
 * '''logical_name''': if '''copy_file''' is present, the name of the file
  in the runtime directory.
 * '''gzip''': send the file in compressed form to 7.0+ clients
  (the file will be sent in uncompressed form to earlier clients).
  [FileCompression#gzipencoding Details here].
 * '''url''': URLs from which the file can be downloaded.
  Use this if you want to mirror your executables on separate servers.
  The executables must be present on the main server,
  at least while '''update_versions''' is run.  This should be URL to the exact files, not a folder/directory structure such as used in your boinc server to store the applications.  You do not need to include any .sig signature files generated when the executable is signed.

If a file doesn't require any of the above attributes,
you don't need to include a '''<file>''' element for it.

If you use '''<gzip/>''' together with '''<url>''',
you must create a gzipped version of the file (physical_name.gz)
and place it alongside each copy of the file.

Other options:
 * '''dont_throttle''': set if the app does its own CPU throttling (e.g., the [VboxApps Virtualbox wrapper]).
 * '''file_prefix''': prepend "X/" to the logical names of input and output files,
  causing them to be placed in subdirectories of the slot directory
  (e.g., "shared" for app versions based on the [VboxApps Virtualbox wrapper]).
  Works only with 7.0+ clients.
 * '''needs_network''': set if the app needs constant network access,
  and hence should not be scheduled if network activity is suspended
  (enforced by client versions 7.0.4+).
 * '''is_wrapper''': the main program is a wrapper;
  hence it uses little CPU time and can be run at above-idle priority
  (this is done by 7.4+ clients).
 * '''beta''': the app version should be sent only to users who
   have agreed (in their project preferences) to accept test app versions.
 * '''api_version''': The version number of the BOINC API used by the app.  Notes:
  * Normally this is obtained automatically by looking for the string API_VERSION in the main-program executable.
    Use this option if you are compressing or otherwise mangling the executable.
  * The API version number is in your BOINC source tree in version.h (Win) or config.h (Unix).

If the application has only one file (the main program),
you don't need a '''version.xml''' file.

If your application includes executable files other than the main program,
make sure that their user execute (u+x) flag is set
(relevant for Unix and Mac versions).

If your application has a graphics program, it must have the logical name 'graphics_app';
use an entry such as the following:

{{{
  <file>
    <physical_name>qcn_graphics_6.65_i686-apple-darwin</physical_name>
    <logical_name>graphics_app</logical_name>
  </file>
}}}