Text file src/cmd/go/testdata/script/README

     1  This file is generated by 'go generate cmd/go'. DO NOT EDIT.
     2  
     3  This directory holds test scripts *.txt run during 'go test cmd/go'.
     4  To run a specific script foo.txt
     5  
     6  	go test cmd/go -run=Script/^foo$
     7  
     8  In general script files should have short names: a few words, not whole sentences.
     9  The first word should be the general category of behavior being tested,
    10  often the name of a go subcommand (list, build, test, ...) or concept (vendor, pattern).
    11  
    12  Each script is a text archive (go doc internal/txtar).
    13  The script begins with an actual command script to run
    14  followed by the content of zero or more supporting files to
    15  create in the script's temporary file system before it starts executing.
    16  
    17  As an example, run_hello.txt says:
    18  
    19  	# hello world
    20  	go run hello.go
    21  	stderr 'hello world'
    22  	! stdout .
    23  
    24  	-- hello.go --
    25  	package main
    26  	func main() { println("hello world") }
    27  
    28  Each script runs in a fresh temporary work directory tree, available to scripts as $WORK.
    29  Scripts also have access to other environment variables, including:
    30  
    31  	GOARCH=<target GOARCH>
    32  	GOCACHE=<actual GOCACHE being used outside the test>
    33  	GOEXE=<executable file suffix: .exe on Windows, empty on other systems>
    34  	GOOS=<target GOOS>
    35  	GOPATH=$WORK/gopath
    36  	GOPROXY=<local module proxy serving from cmd/go/testdata/mod>
    37  	GOROOT=<actual GOROOT>
    38  	TESTGO_GOROOT=<GOROOT used to build cmd/go, for use in tests that may change GOROOT>
    39  	HOME=/no-home
    40  	PATH=<actual PATH>
    41  	TMPDIR=$WORK/tmp
    42  	GODEBUG=<actual GODEBUG>
    43  	devnull=<value of os.DevNull>
    44  	goversion=<current Go version; for example, 1.12>
    45  
    46  On Plan 9, the variables $path and $home are set instead of $PATH and $HOME.
    47  On Windows, the variables $USERPROFILE and $TMP are set instead of
    48  $HOME and $TMPDIR.
    49  
    50  The lines at the top of the script are a sequence of commands to be executed by
    51  a small script engine configured in ../../script_test.go (not the system shell).
    52  
    53  The scripts' supporting files are unpacked relative to $GOPATH/src
    54  (aka $WORK/gopath/src) and then the script begins execution in that directory as
    55  well. Thus the example above runs in $WORK/gopath/src with GOPATH=$WORK/gopath
    56  and $WORK/gopath/src/hello.go containing the listed contents.
    57  
    58  Each line of a script is parsed into a sequence of space-separated command
    59  words, with environment variable expansion within each word and # marking
    60  an end-of-line comment. Additional variables named ':' and '/' are expanded
    61  within script arguments (expanding to the value of os.PathListSeparator and
    62  os.PathSeparator respectively) but are not inherited in subprocess environments.
    63  
    64  Adding single quotes around text keeps spaces in that text from being treated
    65  as word separators and also disables environment variable expansion. Inside a
    66  single-quoted block of text, a repeated single quote indicates a literal single
    67  quote, as in:
    68  
    69      'Don''t communicate by sharing memory.'
    70  
    71  A line beginning with # is a comment and conventionally explains what is being
    72  done or tested at the start of a new section of the script.
    73  
    74  Commands are executed one at a time, and errors are checked for each command;
    75  if any command fails unexpectedly, no subsequent commands in the script are
    76  executed. The command prefix ! indicates that the command on the rest of the
    77  line (typically go or a matching predicate) must fail instead of succeeding.
    78  The command prefix ? indicates that the command may or may not succeed, but the
    79  script should continue regardless.
    80  
    81  The command prefix [cond] indicates that the command on the rest of the line
    82  should only run when the condition is satisfied.
    83  
    84  A condition can be negated: [!root] means to run the rest of the line only if
    85  the user is not root. Multiple conditions may be given for a single command,
    86  for example, '[linux] [amd64] skip'. The command will run if all conditions are
    87  satisfied.
    88  
    89  When TestScript runs a script and the script fails, by default TestScript shows
    90  the execution of the most recent phase of the script (since the last # comment)
    91  and only shows the # comments for earlier phases. For example, here is a
    92  multi-phase script with a bug in it:
    93  
    94  	# GOPATH with p1 in d2, p2 in d2
    95  	env GOPATH=$WORK${/}d1${:}$WORK${/}d2
    96  
    97  	# build & install p1
    98  	env
    99  	go install -i p1
   100  	! stale p1
   101  	! stale p2
   102  
   103  	# modify p2 - p1 should appear stale
   104  	cp $WORK/p2x.go $WORK/d2/src/p2/p2.go
   105  	stale p1 p2
   106  
   107  	# build & install p1 again
   108  	go install -i p11
   109  	! stale p1
   110  	! stale p2
   111  
   112  	-- $WORK/d1/src/p1/p1.go --
   113  	package p1
   114  	import "p2"
   115  	func F() { p2.F() }
   116  	-- $WORK/d2/src/p2/p2.go --
   117  	package p2
   118  	func F() {}
   119  	-- $WORK/p2x.go --
   120  	package p2
   121  	func F() {}
   122  	func G() {}
   123  
   124  The bug is that the final phase installs p11 instead of p1. The test failure looks like:
   125  
   126  	$ go test -run=Script
   127  	--- FAIL: TestScript (3.75s)
   128  	    --- FAIL: TestScript/install_rebuild_gopath (0.16s)
   129  	        script_test.go:223:
   130  	            # GOPATH with p1 in d2, p2 in d2 (0.000s)
   131  	            # build & install p1 (0.087s)
   132  	            # modify p2 - p1 should appear stale (0.029s)
   133  	            # build & install p1 again (0.022s)
   134  	            > go install -i p11
   135  	            [stderr]
   136  	            can't load package: package p11: cannot find package "p11" in any of:
   137  	            	/Users/rsc/go/src/p11 (from $GOROOT)
   138  	            	$WORK/d1/src/p11 (from $GOPATH)
   139  	            	$WORK/d2/src/p11
   140  	            [exit status 1]
   141  	            FAIL: unexpected go command failure
   142  
   143  	        script_test.go:73: failed at testdata/script/install_rebuild_gopath.txt:15 in $WORK/gopath/src
   144  
   145  	FAIL
   146  	exit status 1
   147  	FAIL	cmd/go	4.875s
   148  	$
   149  
   150  Note that the commands in earlier phases have been hidden, so that the relevant
   151  commands are more easily found, and the elapsed time for a completed phase
   152  is shown next to the phase heading. To see the entire execution, use "go test -v",
   153  which also adds an initial environment dump to the beginning of the log.
   154  
   155  Note also that in reported output, the actual name of the per-script temporary directory
   156  has been consistently replaced with the literal string $WORK.
   157  
   158  The cmd/go test flag -testwork (which must appear on the "go test" command line after
   159  standard test flags) causes each test to log the name of its $WORK directory and other
   160  environment variable settings and also to leave that directory behind when it exits,
   161  for manual debugging of failing tests:
   162  
   163  	$ go test -run=Script -work
   164  	--- FAIL: TestScript (3.75s)
   165  	    --- FAIL: TestScript/install_rebuild_gopath (0.16s)
   166  	        script_test.go:223:
   167  	            WORK=/tmp/cmd-go-test-745953508/script-install_rebuild_gopath
   168  	            GOARCH=
   169  	            GOCACHE=/Users/rsc/Library/Caches/go-build
   170  	            GOOS=
   171  	            GOPATH=$WORK/gopath
   172  	            GOROOT=/Users/rsc/go
   173  	            HOME=/no-home
   174  	            TMPDIR=$WORK/tmp
   175  	            exe=
   176  
   177  	            # GOPATH with p1 in d2, p2 in d2 (0.000s)
   178  	            # build & install p1 (0.085s)
   179  	            # modify p2 - p1 should appear stale (0.030s)
   180  	            # build & install p1 again (0.019s)
   181  	            > go install -i p11
   182  	            [stderr]
   183  	            can't load package: package p11: cannot find package "p11" in any of:
   184  	            	/Users/rsc/go/src/p11 (from $GOROOT)
   185  	            	$WORK/d1/src/p11 (from $GOPATH)
   186  	            	$WORK/d2/src/p11
   187  	            [exit status 1]
   188  	            FAIL: unexpected go command failure
   189  
   190  	        script_test.go:73: failed at testdata/script/install_rebuild_gopath.txt:15 in $WORK/gopath/src
   191  
   192  	FAIL
   193  	exit status 1
   194  	FAIL	cmd/go	4.875s
   195  	$
   196  
   197  	$ WORK=/tmp/cmd-go-test-745953508/script-install_rebuild_gopath
   198  	$ cd $WORK/d1/src/p1
   199  	$ cat p1.go
   200  	package p1
   201  	import "p2"
   202  	func F() { p2.F() }
   203  	$
   204  
   205  The available commands are:
   206  cat files...
   207  	concatenate files and print to the script's stdout buffer
   208  
   209  
   210  cc args...
   211  	run the platform C compiler
   212  
   213  
   214  cd dir
   215  	change the working directory
   216  
   217  
   218  chmod perm paths...
   219  	change file mode bits
   220  
   221  	Changes the permissions of the named files or directories to
   222  	be equal to perm.
   223  	Only numerical permissions are supported.
   224  
   225  cmp [-q] file1 file2
   226  	compare files for differences
   227  
   228  	By convention, file1 is the actual data and file2 is the
   229  	expected data.
   230  	The command succeeds if the file contents are identical.
   231  	File1 can be 'stdout' or 'stderr' to compare the stdout or
   232  	stderr buffer from the most recent command.
   233  
   234  cmpenv [-q] file1 file2
   235  	compare files for differences, with environment expansion
   236  
   237  	By convention, file1 is the actual data and file2 is the
   238  	expected data.
   239  	The command succeeds if the file contents are identical
   240  	after substituting variables from the script environment.
   241  	File1 can be 'stdout' or 'stderr' to compare the script's
   242  	stdout or stderr buffer.
   243  
   244  cp src... dst
   245  	copy files to a target file or directory
   246  
   247  	src can include 'stdout' or 'stderr' to copy from the
   248  	script's stdout or stderr buffer.
   249  
   250  echo string...
   251  	display a line of text
   252  
   253  
   254  env [key[=value]...]
   255  	set or log the values of environment variables
   256  
   257  	With no arguments, print the script environment to the log.
   258  	Otherwise, add the listed key=value pairs to the environment
   259  	or print the listed keys.
   260  
   261  exec program [args...] [&]
   262  	run an executable program with arguments
   263  
   264  	Note that 'exec' does not terminate the script (unlike Unix
   265  	shells).
   266  
   267  exists [-readonly] [-exec] file...
   268  	check that files exist
   269  
   270  
   271  go [args...] [&]
   272  	run the 'go' program provided by the script host
   273  
   274  
   275  grep [-count=N] [-q] 'pattern' file
   276  	find lines in a file that match a pattern
   277  
   278  	The command succeeds if at least one match (or the exact
   279  	count, if given) is found.
   280  	The -q flag suppresses printing of matches.
   281  
   282  help [-v] name...
   283  	log help text for commands and conditions
   284  
   285  	To display help for a specific condition, enclose it in
   286  	brackets: 'help [amd64]'.
   287  	To display complete documentation when listing all commands,
   288  	pass the -v flag.
   289  
   290  mkdir path...
   291  	create directories, if they do not already exist
   292  
   293  	Unlike Unix mkdir, parent directories are always created if
   294  	needed.
   295  
   296  mv old new
   297  	rename a file or directory to a new path
   298  
   299  	OS-specific restrictions may apply when old and new are in
   300  	different directories.
   301  
   302  replace [old new]... file
   303  	replace strings in a file
   304  
   305  	The 'old' and 'new' arguments are unquoted as if in quoted
   306  	Go strings.
   307  
   308  rm path...
   309  	remove a file or directory
   310  
   311  	If the path is a directory, its contents are removed
   312  	recursively.
   313  
   314  skip [msg]
   315  	skip the current test
   316  
   317  
   318  sleep duration [&]
   319  	sleep for a specified duration
   320  
   321  	The duration must be given as a Go time.Duration string.
   322  
   323  stale target...
   324  	check that build targets are stale
   325  
   326  
   327  stderr [-count=N] [-q] 'pattern' file
   328  	find lines in the stderr buffer that match a pattern
   329  
   330  	The command succeeds if at least one match (or the exact
   331  	count, if given) is found.
   332  	The -q flag suppresses printing of matches.
   333  
   334  stdout [-count=N] [-q] 'pattern' file
   335  	find lines in the stdout buffer that match a pattern
   336  
   337  	The command succeeds if at least one match (or the exact
   338  	count, if given) is found.
   339  	The -q flag suppresses printing of matches.
   340  
   341  stop [msg]
   342  	stop execution of the script
   343  
   344  	The message is written to the script log, but no error is
   345  	reported from the script engine.
   346  
   347  symlink path -> target
   348  	create a symlink
   349  
   350  	Creates path as a symlink to target.
   351  	The '->' token (like in 'ls -l' output on Unix) is required.
   352  
   353  wait
   354  	wait for completion of background commands
   355  
   356  	Waits for all background commands to complete.
   357  	The output (and any error) from each command is printed to
   358  	the log in the order in which the commands were started.
   359  	After the call to 'wait', the script's stdout and stderr
   360  	buffers contain the concatenation of the background
   361  	commands' outputs.
   362  
   363  
   364  
   365  The available conditions are:
   366  [GOARCH:*]
   367  	runtime.GOARCH == <suffix>
   368  [GODEBUG:*]
   369  	GODEBUG contains <suffix>
   370  [GOEXPERIMENT:*]
   371  	GOEXPERIMENT <suffix> is enabled
   372  [GOOS:*]
   373  	runtime.GOOS == <suffix>
   374  [abscc]
   375  	default $CC path is absolute and exists
   376  [asan]
   377  	GOOS/GOARCH supports -asan
   378  [buildmode:*]
   379  	go supports -buildmode=<suffix>
   380  [case-sensitive]
   381  	$WORK filesystem is case-sensitive
   382  [cc:*]
   383  	go env CC = <suffix> (ignoring the go/env file)
   384  [cgo]
   385  	host CGO_ENABLED
   386  [cgolinkext]
   387  	platform requires external linking for cgo
   388  [compiler:*]
   389  	runtime.Compiler == <suffix>
   390  [cross]
   391  	cmd/go GOOS/GOARCH != GOHOSTOS/GOHOSTARCH
   392  [exec:*]
   393  	<suffix> names an executable in the test binary's PATH
   394  [fuzz]
   395  	GOOS/GOARCH supports -fuzz
   396  [fuzz-instrumented]
   397  	GOOS/GOARCH supports -fuzz with instrumentation
   398  [git]
   399  	the 'git' executable exists and provides the standard CLI
   400  [go-builder]
   401  	GO_BUILDER_NAME is non-empty
   402  [link]
   403  	testenv.HasLink()
   404  [msan]
   405  	GOOS/GOARCH supports -msan
   406  [mustlinkext]
   407  	platform always requires external linking
   408  [net:*]
   409  	can connect to external network host <suffix>
   410  [pielinkext]
   411  	platform requires external linking for PIE
   412  [race]
   413  	GOOS/GOARCH supports -race
   414  [root]
   415  	os.Geteuid() == 0
   416  [short]
   417  	testing.Short()
   418  [symlink]
   419  	testenv.HasSymlink()
   420  [trimpath]
   421  	test binary was built with -trimpath
   422  [verbose]
   423  	testing.Verbose()
   424  
   425  

View as plain text