comparison env/lib/python3.9/site-packages/cwltool/schemas/v1.2.0-dev4/ @ 0:4f3585e2f14b draft default tip

"planemo upload commit 60cee0fc7c0cda8592644e1aad72851dec82c959"
author shellac
date Mon, 22 Mar 2021 18:12:50 +0000
equal deleted inserted replaced
-1:000000000000 0:4f3585e2f14b
1 # Running a Command
3 To accommodate the enormous variety in syntax and semantics for input, runtime
4 environment, invocation, and output of arbitrary programs, a CommandLineTool
5 defines an "input binding" that describes how to translate abstract input
6 parameters to an concrete program invocation, and an "output binding" that
7 describes how to generate output parameters from program output.
9 ## Input binding
11 The tool command line is built by applying command line bindings to the
12 input object. Bindings are listed either as part of an [input
13 parameter](#CommandInputParameter) using the `inputBinding` field, or
14 separately using the `arguments` field of the CommandLineTool.
16 The algorithm to build the command line is as follows. In this algorithm,
17 the sort key is a list consisting of one or more numeric or string
18 elements. Strings are sorted lexicographically based on UTF-8 encoding.
20 1. Collect `CommandLineBinding` objects from `arguments`. Assign a sorting
21 key `[position, i]` where `position` is
22 [`CommandLineBinding.position`](#CommandLineBinding) and `i`
23 is the index in the `arguments` list.
25 2. Collect `CommandLineBinding` objects from the `inputs` schema and
26 associate them with values from the input object. Where the input type
27 is a record, array, or map, recursively walk the schema and input object,
28 collecting nested `CommandLineBinding` objects and associating them with
29 values from the input object.
31 3. Create a sorting key by taking the value of the `position` field at
32 each level leading to each leaf binding object. If `position` is not
33 specified, it is not added to the sorting key. For bindings on arrays
34 and maps, the sorting key must include the array index or map key
35 following the position. If and only if two bindings have the same sort
36 key, the tie must be broken using the ordering of the field or parameter
37 name immediately containing the leaf binding.
39 4. Sort elements using the assigned sorting keys. Numeric entries sort
40 before strings.
42 5. In the sorted order, apply the rules defined in
43 [`CommandLineBinding`](#CommandLineBinding) to convert bindings to actual
44 command line elements.
46 6. Insert elements from `baseCommand` at the beginning of the command
47 line.
49 ## Runtime environment
51 All files listed in the input object must be made available in the runtime
52 environment. The implementation may use a shared or distributed file
53 system or transfer files via explicit download to the host. Implementations
54 may choose not to provide access to files not explicitly specified in the input
55 object or process requirements.
57 Output files produced by tool execution must be written to the
58 **designated output directory**. The initial current working
59 directory when executing the tool must be the designated output
60 directory. The designated output directory should be empty, except
61 for files or directories specified using
62 [InitialWorkDirRequirement](InitialWorkDirRequirement).
64 Files may also be written to the **designated temporary directory**. This
65 directory must be isolated and not shared with other processes. Any files
66 written to the designated temporary directory may be automatically deleted by
67 the workflow platform immediately after the tool terminates.
69 For compatibility, files may be written to the **system temporary directory**
70 which must be located at `/tmp`. Because the system temporary directory may be
71 shared with other processes on the system, files placed in the system temporary
72 directory are not guaranteed to be deleted automatically. A tool
73 must not use the system temporary directory as a backchannel communication with
74 other tools. It is valid for the system temporary directory to be the same as
75 the designated temporary directory.
77 When executing the tool, the tool must execute in a new, empty environment
78 with only the environment variables described below; the child process must
79 not inherit environment variables from the parent process except as
80 specified or at user option.
82 * `HOME` must be set to the designated output directory.
83 * `TMPDIR` must be set to the designated temporary directory.
84 * `PATH` may be inherited from the parent process, except when run in a
85 container that provides its own `PATH`.
86 * Variables defined by [EnvVarRequirement](#EnvVarRequirement)
87 * The default environment of the container, such as when using
88 [DockerRequirement](#DockerRequirement)
90 An implementation may forbid the tool from writing to any location in the
91 runtime environment file system other than the designated temporary directory,
92 system temporary directory, and designated output directory. An implementation
93 may provide read-only input files, and disallow in-place update of input files.
94 The designated temporary directory, system temporary directory and designated
95 output directory may each reside on different mount points on different file
96 systems.
98 An implementation may forbid the tool from directly accessing network
99 resources. Correct tools must not assume any network access unless they have
100 the 'networkAccess' field of a ['NetworkAccess'](#NetworkAccess) requirement set
101 to `true` but even then this does not imply a publically routable IP address or
102 the ability to accept inbound connections.
104 The `runtime` section available in [parameter references](#Parameter_references)
105 and [expressions](#Expressions) contains the following fields. As noted
106 earlier, an implementation may perform deferred resolution of runtime fields by providing
107 opaque strings for any or all of the following fields; parameter references
108 and expressions may only use the literal string value of the field and must
109 not perform computation on the contents.
111 * `runtime.outdir`: an absolute path to the designated output directory
112 * `runtime.tmpdir`: an absolute path to the designated temporary directory
113 * `runtime.cores`: number of CPU cores reserved for the tool process
114 * `runtime.ram`: amount of RAM in mebibytes (2\*\*20) reserved for the tool process
115 * `runtime.outdirSize`: reserved storage space available in the designated output directory
116 * `runtime.tmpdirSize`: reserved storage space available in the designated temporary directory
118 For `cores`, `ram`, `outdirSize` and `tmpdirSize`, if an implementation can't
119 provide the actual number of reserved resources during the expression evaluation time,
120 it should report back the minimal requested amount.
122 See [ResourceRequirement](#ResourceRequirement) for details on how to
123 describe the hardware resources required by a tool.
125 The standard input stream, the standard output stream, and/or the standard error
126 stream may be redirected as described in the [`stdin`](#stdin),
127 [`stdout`](#stdout), and [`stderr`](#stderr) fields.
129 ## Execution
131 Once the command line is built and the runtime environment is created, the
132 actual tool is executed.
134 The standard error stream and standard output stream may be captured by
135 platform logging facilities for storage and reporting.
137 Tools may be multithreaded or spawn child processes; however, when the
138 parent process exits, the tool is considered finished regardless of whether
139 any detached child processes are still running. Tools must not require any
140 kind of console, GUI, or web based user interaction in order to start and
141 run to completion.
143 The exit code of the process indicates if the process completed
144 successfully. By convention, an exit code of zero is treated as success
145 and non-zero exit codes are treated as failure. This may be customized by
146 providing the fields `successCodes`, `temporaryFailCodes`, and
147 `permanentFailCodes`. An implementation may choose to default unspecified
148 non-zero exit codes to either `temporaryFailure` or `permanentFailure`.
150 The exit code of the process is available to expressions in
151 `outputEval` as `runtime.exitCode`.
153 ## Output binding
155 If the output directory contains a file named "cwl.output.json", that file
156 must be loaded and used as the output object. Otherwise, the output object
157 must be generated by walking the parameters listed in `outputs` and
158 applying output bindings to the tool output. Output bindings are
159 associated with output parameters using the `outputBinding` field. See
160 [`CommandOutputBinding`](#CommandOutputBinding) for details.