diff env/lib/python3.9/site-packages/cwltool/schemas/v1.2/invocation.md @ 0:4f3585e2f14b draft default tip

"planemo upload commit 60cee0fc7c0cda8592644e1aad72851dec82c959"

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/env/lib/python3.9/site-packages/cwltool/schemas/v1.2/invocation.md	Mon Mar 22 18:12:50 2021 +0000
@@ -0,0 +1,160 @@
+# Running a Command
+
+To accommodate the enormous variety in syntax and semantics for input, runtime
+environment, invocation, and output of arbitrary programs, a CommandLineTool
+defines an "input binding" that describes how to translate abstract input
+parameters to an concrete program invocation, and an "output binding" that
+describes how to generate output parameters from program output.
+
+## Input binding
+
+The tool command line is built by applying command line bindings to the
+input object.  Bindings are listed either as part of an [input
+parameter](#CommandInputParameter) using the `inputBinding` field, or
+separately using the `arguments` field of the CommandLineTool.
+
+The algorithm to build the command line is as follows.  In this algorithm,
+the sort key is a list consisting of one or more numeric or string
+elements.  Strings are sorted lexicographically based on UTF-8 encoding.
+
+  1. Collect `CommandLineBinding` objects from `arguments`.  Assign a sorting
+  key `[position, i]` where `position` is
+  [`CommandLineBinding.position`](#CommandLineBinding) and `i`
+  is the index in the `arguments` list.
+
+  2. Collect `CommandLineBinding` objects from the `inputs` schema and
+  associate them with values from the input object.  Where the input type
+  is a record, array, or map, recursively walk the schema and input object,
+  collecting nested `CommandLineBinding` objects and associating them with
+  values from the input object.
+
+  3. Create a sorting key by taking the value of the `position` field at
+  each level leading to each leaf binding object.  If `position` is not
+  specified, it is not added to the sorting key.  For bindings on arrays
+  and maps, the sorting key must include the array index or map key
+  following the position.  If and only if two bindings have the same sort
+  key, the tie must be broken using the ordering of the field or parameter
+  name immediately containing the leaf binding.
+
+  4. Sort elements using the assigned sorting keys.  Numeric entries sort
+  before strings.
+
+  5. In the sorted order, apply the rules defined in
+  [`CommandLineBinding`](#CommandLineBinding) to convert bindings to actual
+  command line elements.
+
+  6. Insert elements from `baseCommand` at the beginning of the command
+  line.
+
+## Runtime environment
+
+All files listed in the input object must be made available in the runtime
+environment.  The implementation may use a shared or distributed file
+system or transfer files via explicit download to the host.  Implementations
+may choose not to provide access to files not explicitly specified in the input
+object or process requirements.
+
+Output files produced by tool execution must be written to the
+**designated output directory**.  The initial current working
+directory when executing the tool must be the designated output
+directory.  The designated output directory should be empty, except
+for files or directories specified using
+[InitialWorkDirRequirement](InitialWorkDirRequirement).
+
+Files may also be written to the **designated temporary directory**.  This
+directory must be isolated and not shared with other processes.  Any files
+written to the designated temporary directory may be automatically deleted by
+the workflow platform immediately after the tool terminates.
+
+For compatibility, files may be written to the **system temporary directory**
+which must be located at `/tmp`.  Because the system temporary directory may be
+shared with other processes on the system, files placed in the system temporary
+directory are not guaranteed to be deleted automatically.  A tool
+must not use the system temporary directory as a backchannel communication with
+other tools.  It is valid for the system temporary directory to be the same as
+the designated temporary directory.
+
+When executing the tool, the tool must execute in a new, empty environment
+with only the environment variables described below; the child process must
+not inherit environment variables from the parent process except as
+specified or at user option.
+
+  * `HOME` must be set to the designated output directory.
+  * `TMPDIR` must be set to the designated temporary directory.
+  * `PATH` may be inherited from the parent process, except when run in a
+    container that provides its own `PATH`.
+  * Variables defined by [EnvVarRequirement](#EnvVarRequirement)
+  * The default environment of the container, such as when using
+    [DockerRequirement](#DockerRequirement)
+
+An implementation may forbid the tool from writing to any location in the
+runtime environment file system other than the designated temporary directory,
+system temporary directory, and designated output directory.  An implementation
+may provide read-only input files, and disallow in-place update of input files.
+The designated temporary directory, system temporary directory and designated
+output directory may each reside on different mount points on different file
+systems.
+
+An implementation may forbid the tool from directly accessing network
+resources.  Correct tools must not assume any network access unless they have
+the 'networkAccess' field of a ['NetworkAccess'](#NetworkAccess) requirement set
+to `true` but even then this does not imply a publically routable IP address or
+the ability to accept inbound connections.
+
+The `runtime` section available in [parameter references](#Parameter_references)
+and [expressions](#Expressions) contains the following fields.  As noted
+earlier, an implementation may perform deferred resolution of runtime fields by providing
+opaque strings for any or all of the following fields; parameter references
+and expressions may only use the literal string value of the field and must
+not perform computation on the contents.
+
+  * `runtime.outdir`: an absolute path to the designated output directory
+  * `runtime.tmpdir`: an absolute path to the designated temporary directory
+  * `runtime.cores`:  number of CPU cores reserved for the tool process
+  * `runtime.ram`:    amount of RAM in mebibytes (2\*\*20) reserved for the tool process
+  * `runtime.outdirSize`: reserved storage space available in the designated output directory
+  * `runtime.tmpdirSize`: reserved storage space available in the designated temporary directory
+
+For `cores`, `ram`, `outdirSize` and `tmpdirSize`, if an implementation can't
+provide the actual number of reserved resources during the expression evaluation time,
+it should report back the minimal requested amount.
+
+See [ResourceRequirement](#ResourceRequirement) for details on how to
+describe the hardware resources required by a tool.
+
+The standard input stream, the standard output stream, and/or the standard error
+stream may be redirected as described in the [`stdin`](#stdin),
+[`stdout`](#stdout), and [`stderr`](#stderr) fields.
+
+## Execution
+
+Once the command line is built and the runtime environment is created, the
+actual tool is executed.
+
+The standard error stream and standard output stream may be captured by
+platform logging facilities for storage and reporting.
+
+Tools may be multithreaded or spawn child processes; however, when the
+parent process exits, the tool is considered finished regardless of whether
+any detached child processes are still running.  Tools must not require any
+kind of console, GUI, or web based user interaction in order to start and
+run to completion.
+
+The exit code of the process indicates if the process completed
+successfully.  By convention, an exit code of zero is treated as success
+and non-zero exit codes are treated as failure.  This may be customized by
+providing the fields `successCodes`, `temporaryFailCodes`, and
+`permanentFailCodes`.  An implementation may choose to default unspecified
+non-zero exit codes to either `temporaryFailure` or `permanentFailure`.
+
+The exit code of the process is available to expressions in
+`outputEval` as `runtime.exitCode`.
+
+## Output binding
+
+If the output directory contains a file named "cwl.output.json", that file
+must be loaded and used as the output object.  Otherwise, the output object
+must be generated by walking the parameters listed in `outputs` and
+applying output bindings to the tool output.  Output bindings are
+associated with output parameters using the `outputBinding` field.  See
+[`CommandOutputBinding`](#CommandOutputBinding) for details.