1 This file is generated by 'go generate'. DO NOT EDIT.
2
3 This directory holds test scripts *.txt run during 'go test cmd/<toolname>'.
4 To run a specific script foo.txt
5
6 go test cmd/<toolname> -run=Script/^foo$
7
8 In general script files should have short names: a few words,
9 not whole sentences.
10 The first word should be the general category of behavior being tested,
11 often the name of a go subcommand (build, link, compile, ...) or concept (vendor, pattern).
12
13 Each script is a text archive (go doc internal/txtar).
14 The script begins with an actual command script to run
15 followed by the content of zero or more supporting files to
16 create in the script's temporary file system before it starts executing.
17
18 As an example, run_hello.txt says:
19
20 # hello world
21 go run hello.go
22 stderr 'hello world'
23 ! stdout .
24
25 -- hello.go --
26 package main
27 func main() { println("hello world") }
28
29 Each script runs in a fresh temporary work directory tree, available to scripts as $WORK.
30 Scripts also have access to other environment variables, including:
31
32 GOARCH=<target GOARCH>
33 GOOS=<target GOOS>
34 TMPDIR=$WORK/tmp
35 devnull=<value of os.DevNull>
36 goversion=<current Go version; for example, 1.12>
37
38 On Plan 9, the variables $path and $home are set instead of $PATH and $HOME.
39 On Windows, the variables $USERPROFILE and $TMP are set instead of
40 $HOME and $TMPDIR.
41
42 The lines at the top of the script are a sequence of commands to be executed by
43 a small script engine configured in .../cmd/internal/script/scripttest/run.go (not the system shell).
44
45 Each line of a script is parsed into a sequence of space-separated command
46 words, with environment variable expansion within each word and # marking
47 an end-of-line comment. Additional variables named ':' and '/' are expanded
48 within script arguments (expanding to the value of os.PathListSeparator and
49 os.PathSeparator respectively) but are not inherited in subprocess environments.
50
51 Adding single quotes around text keeps spaces in that text from being treated
52 as word separators and also disables environment variable expansion. Inside a
53 single-quoted block of text, a repeated single quote indicates a literal single
54 quote, as in:
55
56 'Don''t communicate by sharing memory.'
57
58 A line beginning with # is a comment and conventionally explains what is being
59 done or tested at the start of a new section of the script.
60
61 Commands are executed one at a time, and errors are checked for each command;
62 if any command fails unexpectedly, no subsequent commands in the script are
63 executed. The command prefix ! indicates that the command on the rest of the
64 line (typically go or a matching predicate) must fail instead of succeeding.
65 The command prefix ? indicates that the command may or may not succeed, but the
66 script should continue regardless.
67
68 The command prefix [cond] indicates that the command on the rest of the line
69 should only run when the condition is satisfied.
70
71 A condition can be negated: [!root] means to run the rest of the line only if
72 the user is not root. Multiple conditions may be given for a single command,
73 for example, '[linux] [amd64] skip'. The command will run if all conditions are
74 satisfied.
75
76 When TestScript runs a script and the script fails, by default TestScript shows
77 the execution of the most recent phase of the script (since the last # comment)
78 and only shows the # comments for earlier phases.
79
80 Note also that in reported output, the actual name of the per-script temporary directory
81 has been consistently replaced with the literal string $WORK.
82
83 The available commands are:
84 cat files...
85 concatenate files and print to the script's stdout buffer
86
87
88 cc args...
89 run the platform C compiler
90
91
92 cd dir
93 change the working directory
94
95
96 chmod perm paths...
97 change file mode bits
98
99 Changes the permissions of the named files or directories to
100 be equal to perm.
101 Only numerical permissions are supported.
102
103 cmp [-q] file1 file2
104 compare files for differences
105
106 By convention, file1 is the actual data and file2 is the
107 expected data.
108 The command succeeds if the file contents are identical.
109 File1 can be 'stdout' or 'stderr' to compare the stdout or
110 stderr buffer from the most recent command.
111
112 cmpenv [-q] file1 file2
113 compare files for differences, with environment expansion
114
115 By convention, file1 is the actual data and file2 is the
116 expected data.
117 The command succeeds if the file contents are identical
118 after substituting variables from the script environment.
119 File1 can be 'stdout' or 'stderr' to compare the script's
120 stdout or stderr buffer.
121
122 cp src... dst
123 copy files to a target file or directory
124
125 src can include 'stdout' or 'stderr' to copy from the
126 script's stdout or stderr buffer.
127
128 echo string...
129 display a line of text
130
131
132 env [key[=value]...]
133 set or log the values of environment variables
134
135 With no arguments, print the script environment to the log.
136 Otherwise, add the listed key=value pairs to the environment
137 or print the listed keys.
138
139 exec program [args...] [&]
140 run an executable program with arguments
141
142 Note that 'exec' does not terminate the script (unlike Unix
143 shells).
144
145 exists [-readonly] [-exec] file...
146 check that files exist
147
148
149 go [args...] [&]
150 run the 'go' program provided by the script host
151
152
153 grep [-count=N] [-q] 'pattern' file
154 find lines in a file that match a pattern
155
156 The command succeeds if at least one match (or the exact
157 count, if given) is found.
158 The -q flag suppresses printing of matches.
159
160 help [-v] name...
161 log help text for commands and conditions
162
163 To display help for a specific condition, enclose it in
164 brackets: 'help [amd64]'.
165 To display complete documentation when listing all commands,
166 pass the -v flag.
167
168 mkdir path...
169 create directories, if they do not already exist
170
171 Unlike Unix mkdir, parent directories are always created if
172 needed.
173
174 mv old new
175 rename a file or directory to a new path
176
177 OS-specific restrictions may apply when old and new are in
178 different directories.
179
180 replace [old new]... file
181 replace strings in a file
182
183 The 'old' and 'new' arguments are unquoted as if in quoted
184 Go strings.
185
186 rm path...
187 remove a file or directory
188
189 If the path is a directory, its contents are removed
190 recursively.
191
192 skip [msg]
193 skip the current test
194
195
196 sleep duration [&]
197 sleep for a specified duration
198
199 The duration must be given as a Go time.Duration string.
200
201 stderr [-count=N] [-q] 'pattern' file
202 find lines in the stderr buffer that match a pattern
203
204 The command succeeds if at least one match (or the exact
205 count, if given) is found.
206 The -q flag suppresses printing of matches.
207
208 stdout [-count=N] [-q] 'pattern' file
209 find lines in the stdout buffer that match a pattern
210
211 The command succeeds if at least one match (or the exact
212 count, if given) is found.
213 The -q flag suppresses printing of matches.
214
215 stop [msg]
216 stop execution of the script
217
218 The message is written to the script log, but no error is
219 reported from the script engine.
220
221 symlink path -> target
222 create a symlink
223
224 Creates path as a symlink to target.
225 The '->' token (like in 'ls -l' output on Unix) is required.
226
227 wait
228 wait for completion of background commands
229
230 Waits for all background commands to complete.
231 The output (and any error) from each command is printed to
232 the log in the order in which the commands were started.
233 After the call to 'wait', the script's stdout and stderr
234 buffers contain the concatenation of the background
235 commands' outputs.
236
237
238
239 The available conditions are:
240 [GOARCH:*]
241 runtime.GOARCH == <suffix>
242 [GODEBUG:*]
243 GODEBUG contains <suffix>
244 [GOEXPERIMENT:*]
245 GOEXPERIMENT <suffix> is enabled
246 [GOOS:*]
247 runtime.GOOS == <suffix>
248 [asan]
249 GOOS/GOARCH supports -asan
250 [buildmode:*]
251 go supports -buildmode=<suffix>
252 [cgo]
253 host CGO_ENABLED
254 [cgolinkext]
255 platform requires external linking for cgo
256 [compiler:*]
257 runtime.Compiler == <suffix>
258 [cross]
259 cmd/go GOOS/GOARCH != GOHOSTOS/GOHOSTARCH
260 [exec:*]
261 <suffix> names an executable in the test binary's PATH
262 [fuzz]
263 GOOS/GOARCH supports -fuzz
264 [fuzz-instrumented]
265 GOOS/GOARCH supports -fuzz with instrumentation
266 [go-builder]
267 GO_BUILDER_NAME is non-empty
268 [link]
269 testenv.HasLink()
270 [msan]
271 GOOS/GOARCH supports -msan
272 [mustlinkext]
273 platform always requires external linking
274 [pielinkext]
275 platform requires external linking for PIE
276 [race]
277 GOOS/GOARCH supports -race
278 [root]
279 os.Geteuid() == 0
280 [short]
281 testing.Short()
282 [symlink]
283 testenv.HasSymlink()
284 [verbose]
285 testing.Verbose()
286
287
View as plain text