Mercurial > repos > shellac > guppy_basecaller

comparison env/lib/python3.7/site-packages/cwltool/schemas/v1.1/invocation.md @ 2:6af9afd405e9 draft

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
"planemo upload commit 0a63dd5f4d38a1f6944587f52a8cd79874177fc1"
author shellac
date Thu, 14 May 2020 14:56:58 -0400
parents 26e78fe6e8c4
children
comparison
equal deleted inserted replaced
1:75ca89e9b81c 2:6af9afd405e9
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. Future versions
100 of the specification may incorporate optional process requirements that
101 describe the networking needs of a tool.
102
103 The `runtime` section available in [parameter references](#Parameter_references)
104 and [expressions](#Expressions) contains the following fields. As noted
105 earlier, an implementation may perform deferred resolution of runtime fields by providing
106 opaque strings for any or all of the following fields; parameter references
107 and expressions may only use the literal string value of the field and must
108 not perform computation on the contents.
109
110 * `runtime.outdir`: an absolute path to the designated output directory
111 * `runtime.tmpdir`: an absolute path to the designated temporary directory
112 * `runtime.cores`: number of CPU cores reserved for the tool process
113 * `runtime.ram`: amount of RAM in mebibytes (2\*\*20) reserved for the tool process
114 * `runtime.outdirSize`: reserved storage space available in the designated output directory
115 * `runtime.tmpdirSize`: reserved storage space available in the designated temporary directory
116
117 For `cores`, `ram`, `outdirSize` and `tmpdirSize`, if an implementation can't
118 provide the actual number of reserved cores during the expression evaluation time,
119 it should report back the minimal requested amount.
120
121 See [ResourceRequirement](#ResourceRequirement) for details on how to
122 describe the hardware resources required by a tool.
123
124 The standard input stream and standard output stream may be redirected as
125 described in the `stdin` and `stdout` fields.
126
127 ## Execution
128
129 Once the command line is built and the runtime environment is created, the
130 actual tool is executed.
131
132 The standard error stream and standard output stream (unless redirected by
133 setting `stdout` or `stderr`) may be captured by platform logging facilities
134 for storage and reporting.
135
136 Tools may be multithreaded or spawn child processes; however, when the
137 parent process exits, the tool is considered finished regardless of whether
138 any detached child processes are still running. Tools must not require any
139 kind of console, GUI, or web based user interaction in order to start and
140 run to completion.
141
142 The exit code of the process indicates if the process completed
143 successfully. By convention, an exit code of zero is treated as success
144 and non-zero exit codes are treated as failure. This may be customized by
145 providing the fields `successCodes`, `temporaryFailCodes`, and
146 `permanentFailCodes`. An implementation may choose to default unspecified
147 non-zero exit codes to either `temporaryFailure` or `permanentFailure`.
148
149 The exit code of the process is available to expressions in
150 `outputEval` as `runtime.exitCode`.
151
152 ## Output binding
153
154 If the output directory contains a file named "cwl.output.json", that file
155 must be loaded and used as the output object. Otherwise, the output object
156 must be generated by walking the parameters listed in `outputs` and
157 applying output bindings to the tool output. Output bindings are
158 associated with output parameters using the `outputBinding` field. See
159 [`CommandOutputBinding`](#CommandOutputBinding) for details.