Mercurial > repos > shellac > guppy_basecaller

comparison env/lib/python3.7/site-packages/cwltool/schemas/v1.0/invocation.md @ 0:26e78fe6e8c4 draft

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
"planemo upload commit c699937486c35866861690329de38ec1a5d9f783"
author shellac
date Sat, 02 May 2020 07:14:21 -0400
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:26e78fe6e8c4
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 **designated
58 output directory**. The initial current working directory when executing
59 the tool must be the designated output directory.
60
61 Files may also be written to the **designated temporary directory**. This
62 directory must be isolated and not shared with other processes. Any files
63 written to the designated temporary directory may be automatically deleted by
64 the workflow platform immediately after the tool terminates.
65
66 For compatibility, files may be written to the **system temporary directory**
67 which must be located at `/tmp`. Because the system temporary directory may be
68 shared with other processes on the system, files placed in the system temporary
69 directory are not guaranteed to be deleted automatically. A tool
70 must not use the system temporary directory as a backchannel communication with
71 other tools. It is valid for the system temporary directory to be the same as
72 the designated temporary directory.
73
74 When executing the tool, the tool must execute in a new, empty environment
75 with only the environment variables described below; the child process must
76 not inherit environment variables from the parent process except as
77 specified or at user option.
78
79 * `HOME` must be set to the designated output directory.
80 * `TMPDIR` must be set to the designated temporary directory.
81 * `PATH` may be inherited from the parent process, except when run in a
82 container that provides its own `PATH`.
83 * Variables defined by [EnvVarRequirement](#EnvVarRequirement)
84 * The default environment of the container, such as when using
85 [DockerRequirement](#DockerRequirement)
86
87 An implementation may forbid the tool from writing to any location in the
88 runtime environment file system other than the designated temporary directory,
89 system temporary directory, and designated output directory. An implementation
90 may provide read-only input files, and disallow in-place update of input files.
91 The designated temporary directory, system temporary directory and designated
92 output directory may each reside on different mount points on different file
93 systems.
94
95 An implementation may forbid the tool from directly accessing network
96 resources. Correct tools must not assume any network access. Future versions
97 of the specification may incorporate optional process requirements that
98 describe the networking needs of a tool.
99
100 The `runtime` section available in [parameter references](#Parameter_references)
101 and [expressions](#Expressions) contains the following fields. As noted
102 earlier, an implementation may perform deferred resolution of runtime fields by providing
103 opaque strings for any or all of the following fields; parameter references
104 and expressions may only use the literal string value of the field and must
105 not perform computation on the contents.
106
107 * `runtime.outdir`: an absolute path to the designated output directory
108 * `runtime.tmpdir`: an absolute path to the designated temporary directory
109 * `runtime.cores`: number of CPU cores reserved for the tool process
110 * `runtime.ram`: amount of RAM in mebibytes (2\*\*20) reserved for the tool process
111 * `runtime.outdirSize`: reserved storage space available in the designated output directory
112 * `runtime.tmpdirSize`: reserved storage space available in the designated temporary directory
113
114 For `cores`, `ram`, `outdirSize` and `tmpdirSize`, if an implementation can't
115 provide the actual number of reserved cores during the expression evaluation time,
116 it should report back the minimal requested amount.
117
118 See [ResourceRequirement](#ResourceRequirement) for details on how to
119 describe the hardware resources required by a tool.
120
121 The standard input stream and standard output stream may be redirected as
122 described in the `stdin` and `stdout` fields.
123
124 ## Execution
125
126 Once the command line is built and the runtime environment is created, the
127 actual tool is executed.
128
129 The standard error stream and standard output stream (unless redirected by
130 setting `stdout` or `stderr`) may be captured by platform logging facilities
131 for storage and reporting.
132
133 Tools may be multithreaded or spawn child processes; however, when the
134 parent process exits, the tool is considered finished regardless of whether
135 any detached child processes are still running. Tools must not require any
136 kind of console, GUI, or web based user interaction in order to start and
137 run to completion.
138
139 The exit code of the process indicates if the process completed
140 successfully. By convention, an exit code of zero is treated as success
141 and non-zero exit codes are treated as failure. This may be customized by
142 providing the fields `successCodes`, `temporaryFailCodes`, and
143 `permanentFailCodes`. An implementation may choose to default unspecified
144 non-zero exit codes to either `temporaryFailure` or `permanentFailure`.
145
146 ## Output binding
147
148 If the output directory contains a file named "cwl.output.json", that file
149 must be loaded and used as the output object. Otherwise, the output object
150 must be generated by walking the parameters listed in `outputs` and
151 applying output bindings to the tool output. Output bindings are
152 associated with output parameters using the `outputBinding` field. See
153 [`CommandOutputBinding`](#CommandOutputBinding) for details.