Adding upstream version 2:1.19~1.upstream/2%1.19_1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 323 insertions, 0 deletions

diff --git a/man/go-testflag.7 b/man/go-testflag.7
new file mode 100644
index 0000000..aabd409
--- /dev/null
+++ b/man/go-testflag.7
@@ -0,0 +1,323 @@
+.\"                                      Hey, EMACS: -*- nroff -*-
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.TH GO-TESTFLAG 7 "2022-03-15"
+.\" Please adjust this date whenever revising the manpage.
+.SH NAME
+go \- tool for managing Go source code
+.SH DESCRIPTION
+The \(oqgo test\(cq command takes both flags that apply to \(oqgo test\(cq itself
+and flags that apply to the resulting test binary.
+
+Several of the flags control profiling and write an execution profile
+suitable for "go tool pprof"; run "go tool pprof \-h" for more
+information. The \-\-alloc_space, \-\-alloc_objects, and \-\-show_bytes
+options of pprof control how the information is presented.
+
+The following flags are recognized by the \(oqgo test\(cq command and
+control the execution of any test:
+.TP
+.BI \-bench " regexp"
+Run only those benchmarks matching a regular expression.
+By default, no benchmarks are run.
+To run all benchmarks, use \(oq\-bench .\(cq or \(oq\-bench=.\(cq.
+The regular expression is split by unbracketed slash (/)
+characters into a sequence of regular expressions, and each
+part of a benchmark\[cq]s identifier must match the corresponding
+element in the sequence, if any. Possible parents of matches
+are run with b.N=1 to identify sub-benchmarks. For example,
+given \-bench=X/Y, top-level benchmarks matching X are run
+with b.N=1 to find any sub-benchmarks matching Y, which are
+then run in full.
+.TP
+.BI \-benchtime " t"
+Run enough iterations of each benchmark to take \fIt\fP, specified
+as a time.Duration (for example, \-benchtime 1h30s).
+.br
+The default is 1 second (1s).
+.br
+The special syntax \fIN\fPx means to run the benchmark \fIN\fP times
+(for example, \-benchtime 100x).
+.TP
+.BI \-count " n"
+Run each test, benchmark, and fuzz seed \fIn\fP times (default 1).
+.br
+If \-cpu is set, run n times for each GOMAXPROCS value.
+.br
+Examples are always run once. \-count does not apply to
+fuzz tests matched by \-fuzz.
+.TP
+.B \-cover
+Enable coverage analysis.
+.br
+Note that because coverage works by annotating the source
+code before compilation, compilation and test failures with
+coverage enabled may report line numbers that don\(cqt correspond
+to the original sources.
+.TP
+.BR \-covermode " set,count,atomic"
+Set the mode for coverage analysis for the package[s]
+being tested. The default is "set" unless \-race is enabled,
+in which case it is "atomic".
+.br
+The values:
+    set: bool: does this statement run?
+    count: int: how many times does this statement run?
+    atomic: int: count, but correct in multithreaded tests;
+            significantly more expensive.
+.br
+Sets \-cover.
+.TP
+.BI "\-coverpkg " pattern1 , pattern2 , pattern3
+Apply coverage analysis in each test to packages matching the patterns.
+The default is for each test to analyze only the package being tested.
+.br
+See \(oqgo help packages\(cq for a description of package patterns.
+.br
+Sets \-cover.
+.TP
+.BI "\-cpu " 1 , 2 , 4
+Specify a list of GOMAXPROCS values for which the tests, benchmarks or
+fuzz tests should be executed. The default is the current value
+of GOMAXPROCS. \-cpu does not apply to fuzz tests matched by \-fuzz.
+.TP
+.B \-failfast
+Do not start new tests after the first test failure.
+.TP
+.BI \-fuzz " regexp"
+Run the fuzz test matching the regular expression. When specified,
+the command line argument must match exactly one package within the
+main module, and regexp must match exactly one fuzz test within
+that package. Fuzzing will occur after tests, benchmarks, seed corpora
+of other fuzz tests, and examples have completed. See the Fuzzing
+section of the testing package documentation for details.
+.TP
+.BI \-fuzztime " t"
+Run enough iterations of the fuzz target during fuzzing to take \fIt\fP,
+specified as a time.Duration (for example, \-fuzztime 1h30s).
+    The default is to run forever.
+.br
+The special syntax \fIN\fPx means to run the fuzz target \fIN\fP times
+(for example, \-fuzztime 1000x).
+.TP
+.BI \-fuzzminimizetime " t"
+Run enough iterations of the fuzz target during each minimization
+attempt to take \fIt\fP, as specified as a time.Duration (for example,
+\-fuzzminimizetime 30s).
+    The default is 60s.
+.br
+The special syntax \fIN\fPx means to run the fuzz target \fIN\fP times
+(for example, \-fuzzminimizetime 100x).
+.TP
+.B \-json
+Log verbose output and test results in JSON. This presents the
+same information as the \-v flag in a machine-readable format.
+.TP
+.BI \-list " regexp"
+List tests, benchmarks, fuzz tests, or examples matching the regular
+expression. No tests, benchmarks, fuzz tests, or examples will be run.
+This will only list top-level tests. No subtest or subbenchmarks will be
+shown.
+.TP
+.BI \-parallel " n"
+Allow parallel execution of test functions that call t.Parallel, and
+fuzz targets that call t.Parallel when running the seed corpus.
+The value of this flag is the maximum number of tests to run
+simultaneously.
+.br
+While fuzzing, the value of this flag is the maximum number of
+subprocesses that may call the fuzz function simultaneously, regardless of
+whether T.Parallel is called.
+.br
+By default, \-parallel is set to the value of GOMAXPROCS.
+Setting \-parallel to values higher than GOMAXPROCS may cause degraded
+performance due to CPU contention, especially when fuzzing.
+Note that \-parallel only applies within a single test binary.
+The \(oqgo test\(cq command may run tests for different packages
+in parallel as well, according to the setting of the \-p flag
+(see \(oqgo help build\(cq).
+.TP
+.BI \-run " regexp"
+Run only those tests, examples, and fuzz tests matching the regular
+expression. For tests, the regular expression is split by unbracketed
+slash (/) characters into a sequence of regular expressions, and each
+part of a test\(cqs identifier must match the corresponding element in
+the sequence, if any. Note that possible parents of matches are
+run too, so that \-run=X/Y matches and runs and reports the result
+of all tests matching X, even those without sub-tests matching Y,
+because it must run them to look for those sub-tests.
+.TP
+.B \-short
+Tell long-running tests to shorten their run time.
+It is off by default but set during all.bash so that installing
+the Go tree can run a sanity check but not spend time running
+exhaustive tests.
+.TP
+.BR "\-shuffle " off,on,N
+Randomize the execution order of tests and benchmarks.
+It is off by default. If \-shuffle is set to on, then it will seed
+the randomizer using the system clock. If \-shuffle is set to an
+integer N, then N will be used as the seed value. In both cases,
+the seed will be reported for reproducibility.
+.TP
+.BI \-timeout " d"
+If a test binary runs longer than duration \fId\fP, panic.
+.br
+If \fId\fP is 0, the timeout is disabled.
+.br
+The default is 10 minutes (10m).
+.TP
+.B \-v
+Verbose output: log all tests as they are run. Also print all
+text from Log and Logf calls even if the test succeeds.
+.TP
+.BI \-vet " list"
+Configure the invocation of "go vet" during "go test"
+to use the comma-separated list of vet checks.
+.br
+If list is empty, "go test" runs "go vet" with a curated list of
+checks believed to be always worth addressing.
+.br
+If list is "off", "go test" does not run "go vet" at all.
+.P
+The following flags are also recognized by \(oqgo test\(cq and can be used to
+profile the tests during execution:
+.TP
+.B \-benchmem
+Print memory allocation statistics for benchmarks.
+.TP
+.B \-blockprofile \fRblock.out
+Write a goroutine blocking profile to the specified file
+when all tests are complete.
+.br
+Writes test binary as \-c would.
+.TP
+.BI \-blockprofilerate " n"
+Control the detail provided in goroutine blocking profiles by
+calling runtime.SetBlockProfileRate with \fIn\fP.
+.br
+See \(oqgo doc runtime.SetBlockProfileRate\(cq.
+.br
+The profiler aims to sample, on average, one blocking event every
+n nanoseconds the program spends blocked. By default,
+if \-test.blockprofile is set without this flag, all blocking events
+are recorded, equivalent to \-test.blockprofilerate=1.
+.TP
+.B \-coverprofile \fRcover.out
+Write a coverage profile to the file after all tests have passed.
+.br
+Sets \-cover.
+.TP
+.B \-cpuprofile \fRcpu.out
+Write a CPU profile to the specified file before exiting.
+.br
+Writes test binary as \-c would.
+.TP
+.B \-memprofile \fRmem.out
+Write an allocation profile to the file after all tests have passed.
+.br
+Writes test binary as \-c would.
+.TP
+.BI \-memprofilerate " n"
+Enable more precise (and expensive) memory allocation profiles by
+setting runtime.MemProfileRate. See \(oqgo doc runtime.MemProfileRate\(cq.
+To profile all memory allocations, use \-test.memprofilerate=1.
+.TP
+.B \-mutexprofile \fRmutex.out
+Write a mutex contention profile to the specified file
+when all tests are complete.
+.br
+Writes test binary as \-c would.
+.TP
+.BI \-mutexprofilefraction " n"
+Sample 1 in \fIn\fP stack traces of goroutines holding a
+contended mutex.
+.TP
+.B \-outputdir \fIdirectory
+Place output files from profiling in the specified directory,
+by default the directory in which "go test" is running.
+.TP
+.B \-trace trace.out
+Write an execution trace to the specified file before exiting.
+.P
+Each of these flags is also recognized with an optional \(oqtest.\(cq prefix,
+as in \-test.v. When invoking the generated test binary (the result of
+\(oqgo test \-c\(cq) directly, however, the prefix is mandatory.
+
+The \(oqgo test\(cq command rewrites or removes recognized flags,
+as appropriate, both before and after the optional package list,
+before invoking the test binary.
+
+For instance, the command
+
+	go test \-v \-myflag testdata \-cpuprofile=prof.out \-x
+
+will compile the test binary and then run it as
+
+	pkg.test \-test.v \-myflag testdata \-test.cpuprofile=prof.out
+
+(The \-x flag is removed because it applies only to the go command\(cqs
+execution, not to the test itself.)
+
+The test flags that generate profiles (other than for coverage) also
+leave the test binary in pkg.test for use when analyzing the profiles.
+
+When \(oqgo test\(cq runs a test binary, it does so from within the
+corresponding package\(cqs source code directory. Depending on the test,
+it may be necessary to do the same when invoking a generated test
+binary directly. Because that directory may be located within the
+module cache, which may be read-only and is verified by checksums, the
+test must not write to it or any other directory within the module
+unless explicitly requested by the user (such as with the \-fuzz flag,
+which writes failures to testdata/fuzz).
+
+The command-line package list, if present, must appear before any
+flag not known to the go test command. Continuing the example above,
+the package list would have to appear before \-myflag, but could appear
+on either side of \-v.
+
+When \(oqgo test\(cq runs in package list mode, \(oqgo test\(cq caches successful
+package test results to avoid unnecessary repeated running of tests. To
+disable test caching, use any test flag or argument other than the
+cacheable flags. The idiomatic way to disable test caching explicitly
+is to use \-count=1.
+
+To keep an argument for a test binary from being interpreted as a
+known flag or a package name, use \-args (see \(oqgo help test\(cq) which
+passes the remainder of the command line through to the test binary
+uninterpreted and unaltered.
+
+For instance, the command
+
+	go test \-v \-args \-x \-v
+
+will compile the test binary and then run it as
+
+	pkg.test \-test.v \-x \-v
+
+Similarly,
+
+	go test \-args math
+
+will compile the test binary and then run it as
+
+	pkg.test math
+
+In the first example, the \-x and the second \-v are passed through to the
+test binary unchanged and with no effect on the go command itself.
+In the second example, the argument math is passed through to the test
+binary, instead of being interpreted as the package list.
+.SH AUTHOR
+.PP
+This manual page was written by Michael Stapelberg <stapelberg@debian.org>
+and is maintained by the
+Debian Go Compiler Team <team+go-compiler@tracker.debian.org>
+based on the output of \(oqgo help testflag\(cq
+for the Debian project (and may be used by others).