--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/configurationengine/doc/plugins/commandml-plugin/commandml.rst Thu Mar 11 17:04:37 2010 +0200
@@ -0,0 +1,270 @@
+User guide for Command Plugin
+-----------------------------
+
+Introduction
+'''''''''''''
+This page describes how to use ConE command plugin. Command plugin is a ConE plugin,
+which purpose is to run external tools and scripts to generate files to target image.
+Command plugin is configured in CommandML files that describes tools that are run
+and options that are used.
+
+CommandML files are executed by default in **normal** :ref:`invocation phase <implml-common-invocation-phase>`.
+
+CommandML
+'''''''''
+
+The CommandML syntax is a extension of Configuration markup language (confml). The term in confml for this extension
+is implementation method language (implml), which in CommandML case is a xml file.
+
+All input values can be given as ConfML refs or as plain text. Also mixing text and ConfML ref information
+is supported.
+
+ * Namespace: ``http://www.s60.com/xml/commandml/1``
+ * File extension: ``commandml``
+
+.. note::
+
+ More information about :ref:`file extensions <implml-file-extensions>`.
+
+CommandML Elements
+..................
+
+The CommandML model is drawn out as a uml model in below picture.
+
+ .. image:: commandml.jpg
+
+.. note::
+
+ CommandML supports also common ImplML elements. More information about :ref:`ImplML elements <implml-common-elements>`.
+
+<commandml> Element
+**************************
+
+The ``commandml`` element is the root element of the configuration, and acts as a container to the rest of the elements.
+
+Child Elements
+++++++++++++++++++++++++++
+
+==================== ====================== ===============================================================================
+Element Cardinality Description
+==================== ====================== ===============================================================================
+condition 0 .. * Defines a group of commands that are run only if command is evaluated as True.
+command 0 .. * Defines properties for one executable.
+==================== ====================== ===============================================================================
+
+Example
+++++++++++++++++++++++++++
+
+.. code-block:: xml
+
+ <commandml xmlns="http://www.s60.com/xml/commandml/1">
+
+<condition> Element
+**************************
+
+``Condition`` element defines a group of commands that are run only if command is evaluated as True.
+
+
+Child Elements
+++++++++++++++++++++++++++
+
+Condition can contain arbitrary number of commands and they are run in definition order so that next command is executed
+only after the previous has ended.
+
+==================== ====================== ===============================================================================
+Element Cardinality Description
+==================== ====================== ===============================================================================
+command 0 .. * Defines properties for one executable.
+==================== ====================== ===============================================================================
+
+Attributes
+++++++++++++++++++++++++++
+
+Condition has only one attribute ``value`` which can contains any Python code and ConfML refs. Refs are first expanded
+and then the value is evaluated using Python eval function.
+
+==================== ====================== ===============================================================================
+Attribute Required Description
+==================== ====================== ===============================================================================
+value Yes Defines a condition value that can contain any Python code and ConfML refs.
+==================== ====================== ===============================================================================
+
+Example
+++++++++++++++++++++++++++
+
+.. code-block:: xml
+
+ <condition value="${runconfig.notepad} != ''">
+ <command executable="notepad.exe"/>
+ </condition>
+
+This will run notepad.exe only if value in ConfML ref ``runconfig.notepad`` is not empty.
+
+<command> Element
+**************************
+
+``Command`` element defines properties for one executable. Basically it provides same features that Python subprocess
+module. Commands can be defined either inside condition elements and directly under ``commandml``. Running order of
+commands is the same that is defined in commandml file. Definition of those can be found from
+`Python subprocess documentation <http://docs.python.org/library/subprocess.html>`_.
+
+Child Elements
+++++++++++++++++++++++++++
+
+Command element can have arguments, pipes and filters as sub-elements.
+
+==================== ====================== ===============================================================================
+Element Cardinality Description
+==================== ====================== ===============================================================================
+argument 0 .. * Defines argument for executable.
+pipe 0 .. * Defines pipe for executable.
+filter 0 .. * Defines filter for executable.
+==================== ====================== ===============================================================================
+
+
+Attributes
+++++++++++++++++++++++++++
+
+Command element has one mandatory argument ``executable`` and four optional attributes: ``shell``, ``env``, ``cwd``, ``bufsize``.
+
+==================== ====================== ===============================================================================
+Attribute Required Description
+==================== ====================== ===============================================================================
+executable Yes Defines a program to execute. Value can contain any Python code and ConfML refs.
+shell No Defines is the specified command executed through the shell.
+env No Defines the environment variables for the new process.
+cwd No Defines the current directory that will be changed to cwd before command is
+ executed. Note that this directory is not considered when searching the
+ executable, so you can't specify the program's path relative to cwd.
+bufsize No Defines the pipe buffering: 0 means unbuffered, 1 means line buffered,
+ any other positive value means use a buffer of (approximately) that size.
+ A negative bufsize means to use the system default, which usually means
+ fully buffered. The default value for bufsize is 0 (unbuffered).
+==================== ====================== ===============================================================================
+
+Example
+++++++++++++++++++++++++++
+
+.. code-block:: xml
+
+ <command executable="\Preinstallation\preinstallation.exe" cwd="x:\" shell="true" env="{'MYVAR':'123'}">
+
+
+
+<argument> Element
+**************************
+
+``Argument`` element defines one command line argument for it's parent command.
+
+
+Attributes
+++++++++++++++++++++++++++
+
+Value is given in attribute ``value`` and can contain any string value. When executing the command all attributes are
+combined to be a single string that is passed as a parameter to executable.
+
+==================== ====================== ===============================================================================
+Attribute Required Description
+==================== ====================== ===============================================================================
+value Yes Defines a one command line argument for it's parent command.
+==================== ====================== ===============================================================================
+
+Example
+++++++++++++++++++++++++++
+
+.. code-block:: xml
+
+ <argument value="-o output/content" />
+ <argument value="--add-setting-file=c:\temp.txt" />
+ <argument value="${preinstallmeta.product}"/>
+
+<pipe> Element
+**************************
+
+Pipes are used to specify executed program's standard input, output and error file handles.
+
+Attributes
+++++++++++++++++++++++++++
+
+``Pipe`` has two mandatory arguments ``name`` and ``value``.
+
+==================== ====================== ===============================================================================
+Attribute Required Description
+==================== ====================== ===============================================================================
+name Yes Defines the name of the pipe. Possible values are: "stdin", "stdout" and
+ "stderr". That are executed programs' standard input, standard output and
+ standard error file handles, respectively.
+value Yes Value can be either PIPE to indicate that new should be defined or then
+ filename. Stderr additionally can have also value STDOUT, which indicates that
+ the stderr data from the applications should be captured into the same file
+ handle as for stdout.
+==================== ====================== ===============================================================================
+
+Example
+++++++++++++++++++++++++++
+
+.. code-block:: xml
+
+ <pipe name="stdout" value="x:\\logia.txt"/>
+ <pipe name="stderr" value="STDOUT"/>
+
+<filter> Element
+**************************
+
+Filters are used to analyse output of executed command and report the findings to ConE log file. This enables that
+executed program's errors are easily available for users.
+
+Attributes
+++++++++++++++++++++++++++
+
+``Filter`` element has four attributes: ``severity``, ``condition``, ``input`` and ``formatter``.
+
+==================== ====================== ===============================================================================
+Attribute Required Description
+==================== ====================== ===============================================================================
+severity Yes Defines logging level e.g. "info" means that possible findings are reported as
+ info elements. Other options for severity are "warning", "debug", "exception",
+ "error" and "critical". Default value is "info".
+condition Yes Defines a Python regexp pattern that is used to match lines from the
+ defined input pipe. Notice that you can use named groups to get some relevant
+ information stored for formatter use.
+input Yes Input can be either "stdout" or "stderr".
+formatter No Formatter defines how the findings are reported in ConE output. It is
+ sprintf-style string which can contain named groups from condition. If
+ formatter is empty found line is printed as such. See examples below.
+==================== ====================== ===============================================================================
+
+Example
+++++++++++++++++++++++++++
+
+.. code-block:: xml
+
+ <filter severity="info" condition="\s*\'(?P<name>.*)\' => \'(?P<uid>.*)\'" input="stdout" formatter="Installed %(name)s using UID: %(uid)s"/>
+ <filter severity="debug" condition=".*successfully.*" input="stdout"/>
+ <filter severity="error" condition="Installation of \'(?P<name>.*)\' failed! See the log for details and contact Delevopment team." input="stdout" formatter="Install manually %(name)s!"/>
+
+The first one defines that findings are reported as info elements. Condition element defines two named groups "name" and
+"uid" which are also used in formatter when printing information to ConE's log file.
+The second one tries to find any line containing word "successfully" and prints the whole line as debug element.
+The last one print all failed cases as errors and uses again named groups to extract data from input stream.
+
+
+Full example files
+''''''''''''''''''
+
+.. literalinclude:: preinstall.commandml
+ :language: xml
+
+
+XSD
+'''
+
+.. note::
+
+ This will be added later.
+
+
+FAQ
+'''''''''''''
+
+This will be updated based on the questions.