cmd/go: extract the TestScript engine into a standalone package

This change decouples the script engine from both cmd/go and the
testing package; I intend to reuse it in the replacement for the
vcs-test.golang.org server.

This change also adds a few new script commands:

	- 'echo' echoes its arguments, useful for verifying argument expansion.

	- 'cat' prints the contents of files, useful for debugging failing script tests.

	- 'help' displays information about script commands and conditions,
	  reducing the toil of maintaining lists in the README file.

The 'cmp' and 'cmpenv' commands now use internal/diff instead of their
own separate diff implementation.

The 'env' command now writes to the script log instead of the stdout
buffer. (This makes it more consistent with the behavior of other
synchronous builtins.)

The 'stale' command no longer logs output when a target is
unexpectedly non-stale. (However, the ouput of the 'stale' command is
not usually very useful anyway.)

The 'grep', 'stdout', and 'stderr' commands now display matching lines
(like Unix 'grep'), making their negation behavior more consistent
with running real commands on a command-line.

Likewise, the 'cmp' command now always displays differences. That
makes it useful with the '?' prefix to produce diffs for informational
purposes while debugging.

For #27494.

Change-Id: If49fd81d9b922d07c20618a8e2cef908191f9ef6
Reviewed-on: https://go-review.googlesource.com/c/go/+/419875
Reviewed-by: Russ Cox <rsc@golang.org>
Auto-Submit: Bryan Mills <bcmills@google.com>
Run-TryBot: Bryan Mills <bcmills@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>

1 files changed, 315 insertions, 157 deletions

diff --git a/src/cmd/go/testdata/script/README b/src/cmd/go/testdata/script/README
index 93c0867d19..edbf645476 100644
--- a/src/cmd/go/testdata/script/README
+++ b/src/cmd/go/testdata/script/README
@@ -1,3 +1,5 @@
+This file is generated by 'go generate cmd/go'. DO NOT EDIT.
+
 This directory holds test scripts *.txt run during 'go test cmd/go'.
 To run a specific script foo.txt
 
@@ -24,7 +26,7 @@ As an example, run_hello.txt says:
 	func main() { println("hello world") }
 
 Each script runs in a fresh temporary work directory tree, available to scripts as $WORK.
-Scripts also have access to these other environment variables:
+Scripts also have access to other environment variables, including:
 
 	GOARCH=<target GOARCH>
 	GOCACHE=<actual GOCACHE being used outside the test>
@@ -39,7 +41,6 @@ Scripts also have access to these other environment variables:
 	PATH=<actual PATH>
 	TMPDIR=$WORK/tmp
 	GODEBUG=<actual GODEBUG>
-	GOCOVERDIR=<current setting of GOCOVERDIR>
 	devnull=<value of os.DevNull>
 	goversion=<current Go version; for example, 1.12>
 
@@ -47,173 +48,44 @@ On Plan 9, the variables $path and $home are set instead of $PATH and $HOME.
 On Windows, the variables $USERPROFILE and $TMP are set instead of
 $HOME and $TMPDIR.
 
-In addition, variables named ':' and '/' are expanded within script arguments
-(expanding to the value of os.PathListSeparator and os.PathSeparator
-respectively) but are not inherited in subprocess environments.
+The lines at the top of the script are a sequence of commands to be executed by
+a small script engine configured in ../../script_test.go (not the system shell).
 
 The scripts' supporting files are unpacked relative to $GOPATH/src
 (aka $WORK/gopath/src) and then the script begins execution in that directory as
 well. Thus the example above runs in $WORK/gopath/src with GOPATH=$WORK/gopath
 and $WORK/gopath/src/hello.go containing the listed contents.
 
-The lines at the top of the script are a sequence of commands to be executed
-by a tiny script engine in ../../script_test.go (not the system shell).
-The script stops and the overall test fails if any particular command fails.
+Each line of a script is parsed into a sequence of space-separated command
+words, with environment variable expansion within each word and # marking
+an end-of-line comment. Additional variables named ':' and '/' are expanded
+within script arguments (expanding to the value of os.PathListSeparator and
+os.PathSeparator respectively) but are not inherited in subprocess environments.
 
-Each line is parsed into a sequence of space-separated command words,
-with environment variable expansion and # marking an end-of-line comment.
 Adding single quotes around text keeps spaces in that text from being treated
-as word separators and also disables environment variable expansion.
-Inside a single-quoted block of text, a repeated single quote indicates
-a literal single quote, as in:
-
-	'Don''t communicate by sharing memory.'
+as word separators and also disables environment variable expansion. Inside a
+single-quoted block of text, a repeated single quote indicates a literal single
+quote, as in:
 
-A line beginning with # is a comment and conventionally explains what is
-being done or tested at the start of a new phase in the script.
+    'Don''t communicate by sharing memory.'
 
-The command prefix ! indicates that the command on the rest of the line
-(typically go or a matching predicate) must fail, not succeed. Only certain
-commands support this prefix. They are indicated below by [!] in the synopsis.
+A line beginning with # is a comment and conventionally explains what is being
+done or tested at the start of a new section of the script.
 
-The command prefix ? indicates that the command on the rest of the line
-may or may not succeed, but the test should continue regardless.
-Commands that support this prefix are indicated by [?].
+Commands are executed one at a time, and errors are checked for each command;
+if any command fails unexpectedly, no subsequent commands in the script are
+executed. The command prefix ! indicates that the command on the rest of the
+line (typically go or a matching predicate) must fail instead of succeeding.
+The command prefix ? indicates that the command may or may not succeed, but the
+script should continue regardless.
 
 The command prefix [cond] indicates that the command on the rest of the line
-should only run when the condition is satisfied. The available conditions are:
-
- - GOOS and GOARCH values, like [386], [windows], and so on.
- - Compiler names, like [gccgo], [gc].
- - Test environment details:
-   - [short] for testing.Short()
-   - [cgo], [msan], [asan], [race] for whether cgo, msan, asan, and the race detector can be used
-   - [fuzz] for whether 'go test -fuzz' can be used at all
-   - [fuzz-instrumented] for whether 'go test -fuzz' uses coverage-instrumented binaries
-   - [net] for whether the external network can be used
-   - [link] for testenv.HasLink()
-   - [root] for os.Geteuid() == 0
-   - [symlink] for testenv.HasSymlink()
-   - [case-sensitive] for whether the file system is case-sensitive
-   - [exec:prog] for whether prog is available for execution (found by exec.LookPath)
-   - [GODEBUG:value] for whether value is one of the comma-separated entries in the GODEBUG variable
-   - [buildmode:value] for whether -buildmode=value is supported
-   - [trimpath] for whether the 'go' binary was built with -trimpath
-   - [mismatched-goroot] for whether the test's GOROOT_FINAL does not match the real GOROOT
-   - [GOEXPERIMENT:expname] for whether the GOEXPERIMENT 'expname' is enabled
-
-A condition can be negated: [!short] means to run the rest of the line
-when testing.Short() is false. Multiple conditions may be given for a single
-command, for example, '[linux] [amd64] skip'. The command will run if all conditions
-are satisfied.
-
-The commands are:
-
-- [! | ?] cc args... [&]
-  Run the C compiler, the platform specific flags (i.e. `go env GOGCCFLAGS`) will be
-  added automatically before args.
-
-- cd dir
-  Change to the given directory for future commands.
-  The directory must use slashes as path separator.
-
-- chmod perm path...
-  Change the permissions of the files or directories named by the path arguments
-  to be equal to perm. Only numerical permissions are supported.
-
-- [! | ?] cmp file1 file2
-  Check that the named files have (or do not have) the same content.
-  By convention, file1 is the actual data and file2 the expected data.
-  File1 can be "stdout" or "stderr" to use the standard output or standard error
-  from the most recent exec or go command.
-  (If the file contents differ and the command is not negated,
-  the failure prints a diff.)
-
-- [! | ?] cmpenv file1 file2
-  Like cmp, but environment variables are substituted in the file contents
-  before the comparison. For example, $GOOS is replaced by the target GOOS.
-
-- [! | ?] cp src... dst
-  Copy the listed files to the target file or existing directory.
-  src can include "stdout" or "stderr" to use the standard output or standard error
-  from the most recent exec or go command.
-
-- env [-r] [key=value...]
-  With no arguments, print the environment to stdout
-  (useful for debugging and for verifying initial state).
-  Otherwise add the listed key=value pairs to the environment.
-  The -r flag causes the values to be escaped using regexp.QuoteMeta
-  before being recorded.
-
-- [! | ?] exec program [args...] [&]
-  Run the given executable program with the arguments.
-  It must (or must not) succeed.
-  Note that 'exec' does not terminate the script (unlike in Unix shells).
-
-  If the last token is '&', the program executes in the background. The standard
-  output and standard error of the previous command is cleared, but the output
-  of the background process is buffered — and checking of its exit status is
-  delayed — until the next call to 'wait', 'skip', or 'stop' or the end of the
-  test. If any background processes remain at the end of the test, they
-  are terminated using os.Interrupt (if supported) or os.Kill and the test
-  must not depend upon their exit status.
-
-- [!] exists [-readonly] [-exec] file...
-  Each of the listed files or directories must (or must not) exist.
-  If -readonly is given, the files or directories must be unwritable.
-  If -exec is given, the files or directories must be executable.
-
-- [! | ?] go args... [&]
-  Run the (test copy of the) go command with the given arguments.
-  It must (or must not) succeed.
-
-- [!] grep [-count=N] [-q] pattern file
-  The file's content must (or must not) match the regular expression pattern.
-  For positive matches, -count=N specifies an exact number of matches to require.
-  The -q flag disables printing the file content on a mismatch.
-
-- mkdir path...
-  Create the listed directories, if they do not already exists.
-
-- mv path1 path2
-  Rename path1 to path2. OS-specific restrictions may apply when path1 and path2
-  are in different directories.
-
-- rm file...
-  Remove the listed files or directories.
-
-- skip [message]
-  Mark the test skipped, including the message if given.
-
-- sleep duration
-  Sleep for the given duration (a time.Duration string).
-  (Tests should generally poll instead of sleeping, but sleeping may sometimes
-  be necessary, for example, to ensure that modified files have unique mtimes.)
-
-- [!] stale path...
-  The packages named by the path arguments must (or must not)
-  be reported as "stale" by the go command.
-
-- [!] stderr [-count=N] pattern
-  Apply the grep command (see above) to the standard error
-  from the most recent exec, go, or wait command.
-
-- [!] stdout [-count=N] pattern
-  Apply the grep command (see above) to the standard output
-  from the most recent exec, go, wait, or env command.
-
-- stop [message]
-  Stop the test early (marking it as passing), including the message if given.
-
-- symlink file -> target
-  Create file as a symlink to target. The -> (like in ls -l output) is required.
-
-- wait
-  Wait for all 'exec' and 'go' commands started in the background (with the '&'
-  token) to exit, and display success or failure status for them.
-  After a call to wait, the 'stderr' and 'stdout' commands will apply to the
-  concatenation of the corresponding streams of the background commands,
-  in the order in which those commands were started.
+should only run when the condition is satisfied.
+
+A condition can be negated: [!root] means to run the rest of the line only if
+the user is not root. Multiple conditions may be given for a single command,
+for example, '[linux] [amd64] skip'. The command will run if all conditions are
+satisfied.
 
 When TestScript runs a script and the script fails, by default TestScript shows
 the execution of the most recent phase of the script (since the last # comment)
@@ -221,7 +93,7 @@ and only shows the # comments for earlier phases. For example, here is a
 multi-phase script with a bug in it:
 
 	# GOPATH with p1 in d2, p2 in d2
-	env GOPATH=$WORK/d1${:}$WORK/d2
+	env GOPATH=$WORK${/}d1${:}$WORK${/}d2
 
 	# build & install p1
 	env
@@ -331,3 +203,289 @@ for manual debugging of failing tests:
 	func F() { p2.F() }
 	$
 
+The available commands are:
+addcrlf file...
+	convert line endings to CRLF
+
+
+cat files...
+	concatenate files and print to the script's stdout buffer
+
+
+cc args...
+	run the platform C compiler
+
+
+cd dir
+	change the working directory
+
+
+chmod perm paths...
+	change file mode bits
+
+	Changes the permissions of the named files or directories to
+	be equal to perm.
+	Only numerical permissions are supported.
+
+cmp [-q] file1 file2
+	compare files for differences
+
+	By convention, file1 is the actual data and file2 is the
+	expected data.
+	The command succeeds if the file contents are identical.
+	File1 can be 'stdout' or 'stderr' to compare the stdout or
+	stderr buffer from the most recent command.
+
+cmpenv [-q] file1 file2
+	compare files for differences, with environment expansion
+
+	By convention, file1 is the actual data and file2 is the
+	expected data.
+	The command succeeds if the file contents are identical
+	after substituting variables from the script environment.
+	File1 can be 'stdout' or 'stderr' to compare the script's
+	stdout or stderr buffer.
+
+cp src... dst
+	copy files to a target file or directory
+
+	src can include 'stdout' or 'stderr' to copy from the
+	script's stdout or stderr buffer.
+
+echo string...
+	display a line of text
+
+
+env [key[=value]...]
+	set or log the values of environment variables
+
+	With no arguments, print the script environment to the log.
+	Otherwise, add the listed key=value pairs to the environment
+	or print the listed keys.
+
+exec program [args...] [&]
+	run an executable program with arguments
+
+	Note that 'exec' does not terminate the script (unlike Unix
+	shells).
+
+exists [-readonly] [-exec] file...
+	check that files exist
+
+
+go [args...] [&]
+	run the 'go' program provided by the script host
+
+
+grep [-count=N] [-q] 'pattern' file
+	find lines in a file that match a pattern
+
+	The command succeeds if at least one match (or the exact
+	count, if given) is found.
+	The -q flag suppresses printing of matches.
+
+help [-v] name...
+	log help text for commands and conditions
+
+	To display help for a specific condition, enclose it in
+	brackets: 'help [amd64]'.
+	To display complete documentation when listing all commands,
+	pass the -v flag.
+
+mkdir path...
+	create directories, if they do not already exist
+
+	Unlike Unix mkdir, parent directories are always created if
+	needed.
+
+mv old new
+	rename a file or directory to a new path
+
+	OS-specific restrictions may apply when old and new are in
+	different directories.
+
+rm path...
+	remove a file or directory
+
+	If the path is a directory, its contents are removed
+	recursively.
+
+skip [msg]
+	skip the current test
+
+
+sleep duration [&]
+	sleep for a specified duration
+
+	The duration must be given as a Go time.Duration string.
+
+stale target...
+	check that build targets are stale
+
+
+stderr [-count=N] [-q] 'pattern' file
+	find lines in the stderr buffer that match a pattern
+
+	The command succeeds if at least one match (or the exact
+	count, if given) is found.
+	The -q flag suppresses printing of matches.
+
+stdout [-count=N] [-q] 'pattern' file
+	find lines in the stdout buffer that match a pattern
+
+	The command succeeds if at least one match (or the exact
+	count, if given) is found.
+	The -q flag suppresses printing of matches.
+
+stop [msg]
+	stop execution of the script
+
+	The message is written to the script log, but no error is
+	reported from the script engine.
+
+symlink path -> target
+	create a symlink
+
+	Creates path as a symlink to target.
+	The '->' token (like in 'ls -l' output on Unix) is required.
+
+wait 
+	wait for completion of background commands
+
+	Waits for all background commands to complete.
+	The output (and any error) from each command is printed to
+	the log in the order in which the commands were started.
+	After the call to 'wait', the script's stdout and stderr
+	buffers contain the concatenation of the background
+	commands' outputs.
+
+
+
+The available conditions are:
+[386]
+	host GOARCH=386
+[GODEBUG:*]
+	GODEBUG contains <suffix>
+[GOEXPERIMENT:*]
+	GOEXPERIMENT <suffix> is enabled
+[aix]
+	host GOOS=aix
+[amd64]
+	host GOARCH=amd64
+[amd64p32]
+	host GOARCH=amd64p32
+[android]
+	host GOOS=android
+[arm]
+	host GOARCH=arm
+[arm64]
+	host GOARCH=arm64
+[arm64be]
+	host GOARCH=arm64be
+[armbe]
+	host GOARCH=armbe
+[asan]
+	GOOS/GOARCH supports -asan
+[buildmode:*]
+	go supports -buildmode=<suffix>
+[case-sensitive]
+	$WORK filesystem is case-sensitive
+[cgo]
+	host CGO_ENABLED
+[cross]
+	cmd/go GOOS/GOARCH != GOHOSTOS/GOHOSTARCH
+[darwin]
+	host GOOS=darwin
+[dragonfly]
+	host GOOS=dragonfly
+[exec:*]
+	<suffix> names an executable in the test binary's PATH
+[freebsd]
+	host GOOS=freebsd
+[fuzz]
+	GOOS/GOARCH supports -fuzz
+[fuzz-instrumented]
+	GOOS/GOARCH supports -fuzz with instrumentation
+[gc]
+	runtime.Compiler == "gc"
+[gccgo]
+	runtime.Compiler == "gccgo"
+[hurd]
+	host GOOS=hurd
+[illumos]
+	host GOOS=illumos
+[ios]
+	host GOOS=ios
+[js]
+	host GOOS=js
+[link]
+	testenv.HasLink()
+[linux]
+	host GOOS=linux
+[loong64]
+	host GOARCH=loong64
+[mips]
+	host GOARCH=mips
+[mips64]
+	host GOARCH=mips64
+[mips64le]
+	host GOARCH=mips64le
+[mips64p32]
+	host GOARCH=mips64p32
+[mips64p32le]
+	host GOARCH=mips64p32le
+[mipsle]
+	host GOARCH=mipsle
+[mismatched-goroot]
+	test's GOROOT_FINAL does not match the real GOROOT
+[msan]
+	GOOS/GOARCH supports -msan
+[nacl]
+	host GOOS=nacl
+[net]
+	testenv.HasExternalNetwork()
+[netbsd]
+	host GOOS=netbsd
+[openbsd]
+	host GOOS=openbsd
+[plan9]
+	host GOOS=plan9
+[ppc]
+	host GOARCH=ppc
+[ppc64]
+	host GOARCH=ppc64
+[ppc64le]
+	host GOARCH=ppc64le
+[race]
+	GOOS/GOARCH supports -race
+[riscv]
+	host GOARCH=riscv
+[riscv64]
+	host GOARCH=riscv64
+[root]
+	os.Geteuid() == 0
+[s390]
+	host GOARCH=s390
+[s390x]
+	host GOARCH=s390x
+[short]
+	testing.Short()
+[solaris]
+	host GOOS=solaris
+[sparc]
+	host GOARCH=sparc
+[sparc64]
+	host GOARCH=sparc64
+[symlink]
+	testenv.HasSymlink()
+[trimpath]
+	test binary was built with -trimpath
+[verbose]
+	testing.Verbose()
+[wasm]
+	host GOARCH=wasm
+[windows]
+	host GOOS=windows
+[zos]
+	host GOOS=zos
+