Mercurial > repos > shellac > sam_consensus_v3
diff env/lib/python3.9/site-packages/cwltool/schemas/v1.2.0-dev3/invocation.md @ 0:4f3585e2f14b draft default tip
"planemo upload commit 60cee0fc7c0cda8592644e1aad72851dec82c959"
author | shellac |
---|---|
date | Mon, 22 Mar 2021 18:12:50 +0000 |
parents | |
children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/env/lib/python3.9/site-packages/cwltool/schemas/v1.2.0-dev3/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.