==========
Claun help
==========

Application entity
==================

:Author: Jiri Chadima
:Version: 2012/04/17

Description
-----------

Information about applications is stored in **couchDB** as a JSON document.
By using the administration form, you can let the server create the document
for you.

A full example application document can be seen in the application.json_
file. Every application has its own document. Some fields in the document
are generated by the server. They are described in the appropriate module.

Form fields
----------------

The fields in the **application** form are:
  - **Name** - Humanly readable name of the application which can should not contain local characters. (mandatory)
  - **Description** - Description of the application. It can be a longer text and the field supports HTML. (optional)
  - **Framework** - This section is mandatory and denotes what framework for distributed applications does this application use.
    You can specify more framework configurations in *Frameworks and Controllers* tab.

    - **Name** - Name of the framework.
    - **Base configuration** - Name of the basic configuration.

  - **Optional additional framework configuration** - A key: value object where you can override certain configuration keys from the configuration stated in the framework section. (optional)
    For particular values, see `Frameworks and Controllers documentation`_.
  - **Controller** - Similar to the framework section, this specifies what controller program the application uses (i. e. trackd).
    For some applications the additional controller software might not be required.

    - **Name** - Name of the controller program.
    - **Base configuration** - Name of the controller program configuration.
    - **Survive crash?** - Boolean attribute, that says if the application can survive crashing of the controller program. If false, than
      if the controller stops working, the application will be stopped too. If true, it is possible to restart the controller and the application will
      work again.

  - **Optional additional controller configuration** - In this key: value object, you can override the options from the configuration stated in the controller section. (optional)
    For particular values, see `Frameworks and Controllers documentation`_.
  - **Platforms** - This section contains information on how to run the application on different platforms.
    For every platform there is a separate section named after the platform (i. e. "gentoo", or "windows-x86") containing information required
    to run the application on this platform. Attributes are usually platform specific.

    For \*nix based systems, these are:
    
    +----------+---------------------------------------------------------------+
    | Name     | Description                                                   |
    +==========+===============================================================+
    | directory| Absolute path to the working directory                        |
    +----------+---------------------------------------------------------------+
    | binary   | Absolute path to the binary                                   |
    +----------+---------------------------------------------------------------+
    | md5sum   | Optional md5checksum of the binary. If it won't match during  |
    |          | the startup, the application won't be run. If not present, the|
    |          | check is omitted                                              |
    +----------+---------------------------------------------------------------+

  - **Parameters** - Application parameters that have no relation to the used framework (i. e. command line switches, input files etc.)
    Every parameter can have the following options:

    - **Name** - name of the parameter for the application. For example '--model' (The leading dashes have to be present)
    - **Human name** - Name that is displayed to the user, like 'Map file' or 'Number of animals'
    - **Type** - This field specifies how the user could influence the parameter's value. If you just need to pass a single value that
      a user can not change, use dropdown with one value.

    +-----------+--------------------------------------------------------------+
    | Name      | Description                                                  |
    +===========+==============================================================+
    | dropdown  | You provide multiple options and user has to choose one.     |
    |           | It is possible to pick a default one that is pre-selected.   |
    +-----------+--------------------------------------------------------------+
    | slider    | Numeric (float/integer) value in a range                     |
    +-----------+--------------------------------------------------------------+
    | boolean   | Toggle button, value is either on or off                     |
    +-----------+--------------------------------------------------------------+

    - **Processing type** - This specifies how the parameter will be passed to the application.

    +-----------+--------------------------------------------------------------+
    | Name      | Description                                                  |
    +===========+==============================================================+
    | cmd       | This is named command line attribute (uses the 'name' field):|
    |           | './binary name value' (If the param name is for example "-i",|
    |           | you have to **explicitly** set the name to "-i")             |
    +-----------+--------------------------------------------------------------+
    | cmdnospace| Same as 'cmd' option, only places no space between the name  |
    |           | and value: './binary namevalue'                              |
    +-----------+--------------------------------------------------------------+
    | cmdnoname | This is the command line attribute without name:             |
    |           | './binary value'                                             |
    +-----------+--------------------------------------------------------------+
    | envvar    | Pass the argument as the environment variable: 'name=value'  |
    +-----------+--------------------------------------------------------------+

      For particular implementation, please see the module responsible for running the application on the target machines.

    - **Help text** - Some helpful text that can explain what the parameter does.
    - **User editable** - Whether a user can edit the parameter; you may want some parameters to be fixed to some value
  - **Visible** - If the application is visible in the list of all applications. (mandatory)


.. _application.json: application.json
.. _`Frameworks and Controllers documentation`: /distribappcontrol/admin/help/index.html