Mercurial > repos > shellac > sam_consensus_v3
comparison env/lib/python3.9/site-packages/cwltool/schemas/v1.2.0-dev2/invocation.md @ 0:4f3585e2f14b draft default tip
"planemo upload commit 60cee0fc7c0cda8592644e1aad72851dec82c959"
author | shellac |
---|---|
date | Mon, 22 Mar 2021 18:12:50 +0000 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:4f3585e2f14b |
---|---|
1 # Running a Command | |
2 | |
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. | |
8 | |
9 ## Input binding | |
10 | |
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. | |
15 | |
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. | |
19 | |
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. | |
24 | |
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. | |
30 | |
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. | |
38 | |
39 4. Sort elements using the assigned sorting keys. Numeric entries sort | |
40 before strings. | |
41 | |
42 5. In the sorted order, apply the rules defined in | |
43 [`CommandLineBinding`](#CommandLineBinding) to convert bindings to actual | |
44 command line elements. | |
45 | |
46 6. Insert elements from `baseCommand` at the beginning of the command | |
47 line. | |
48 | |
49 ## Runtime environment | |
50 | |
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. | |
56 | |
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). | |
63 | |
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. | |
68 | |
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. | |
76 | |
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. | |
81 | |
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) | |
89 | |
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. | |
97 | |
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. | |
103 | |
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. | |
110 | |
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 | |
117 | |
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. | |
121 | |
122 See [ResourceRequirement](#ResourceRequirement) for details on how to | |
123 describe the hardware resources required by a tool. | |
124 | |
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. | |
128 | |
129 ## Execution | |
130 | |
131 Once the command line is built and the runtime environment is created, the | |
132 actual tool is executed. | |
133 | |
134 The standard error stream and standard output stream may be captured by | |
135 platform logging facilities for storage and reporting. | |
136 | |
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. | |
142 | |
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`. | |
149 | |
150 The exit code of the process is available to expressions in | |
151 `outputEval` as `runtime.exitCode`. | |
152 | |
153 ## Output binding | |
154 | |
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. |