fate: document TARGET_EXEC and its usage
[ffmpeg.git] / doc / fate.texi
1 \input texinfo @c -*- texinfo -*-
2
3 @settitle FATE Automated Testing Environment
4 @titlepage
5 @center @titlefont{FATE Automated Testing Environment}
6 @end titlepage
7
8 @top
9
10 @contents
11
12 @chapter Introduction
13
14 FATE provides a regression testsuite embedded within the Libav build system.
15 It can be run locally and optionally configured to send reports to a web
16 aggregator and viewer @url{http://fate.libav.org}.
17
18 It is advised to run FATE before submitting patches to the current codebase
19 and provide new tests when submitting patches to add additional features.
20
21 @chapter Running FATE
22
23 @section Samples and References
24 In order to run, FATE needs a large amount of data (samples and references)
25 that is provided separately from the actual source distribution.
26
27 To inform the build system about the testsuite location, pass
28 @option{--samples=<path to the samples>} to @command{configure} or set the
29 @var{SAMPLES} Make variable or the @var{LIBAV_SAMPLES} environment variable
30 to a suitable value.
31
32 To use a custom wrapper to run the test, pass @option{--target-exec} to
33 @command{configure} or set the @var{TARGET_EXEC} Make variable.
34
35 The dataset is available through @command{rsync}, is possible to fetch
36 the current sample using the straight rsync command or through a specific
37 @ref{Makefile target}.
38
39 @example
40 # rsync -aL rsync://fate-suite.libav.org/fate-suite/ fate-suite
41 @end example
42
43 @example
44 # make fate-rsync SAMPLES=fate-suite
45 @end example
46
47
48 @chapter Manual Run
49 FATE regression test can be run through @command{make}.
50 Specific Makefile targets and Makefile variables are available:
51
52 @anchor{Makefile target}
53 @section FATE Makefile targets
54 @table @option
55 @item fate-list
56 List all fate/regression test targets.
57 @item fate-rsync
58 Shortcut to download the fate test samples to the specified testsuite location.
59 @item fate
60 Run the FATE test suite (requires the fate-suite dataset).
61 @end table
62
63 @section FATE Makefile variables
64 @table @option
65 @item V
66 Verbosity level, can be set to 0, 1 or 2.
67 @table @option
68     @item 0
69     show just the test arguments
70     @item 1
71     show just the command used in the test
72     @item 2
73     show everything
74 @end table
75 @item SAMPLES
76 Specify or override the path to the FATE samples at make time, it has a
77 meaning only while running the regression tests.
78 @item THREADS
79 Specify how many threads to use while running regression tests, it is
80 quite useful to detect thread-related regressions.
81 @item CPUFLAGS
82 Specify a mask to be applied to autodetected CPU flags.
83 @item TARGET_EXEC
84 Specify or override the wrapper used to run the tests.
85 @end table
86
87 @example
88     make V=1 SAMPLES=/var/fate/samples THREADS=2 CPUFLAGS=mmx fate
89 @end example
90
91 @chapter Automated Tests
92 In order to automatically testing specific configurations, e.g. multiple
93 compilers, @command{tests/fate.sh} is provided.
94
95 This shell script builds Libav, runs the regression tests and prepares
96 a report that can be sent to @url{http://fate.libav.org/} or directly
97 examined locally.
98
99 @section Testing Profiles
100 The configuration file passed to @command{fate.sh} is shell scripts as well.
101
102 It must provide at least a @var{slot} identifier, the @var{repo} from
103 which fetch the sources, the @var{samples} directory, a @var{workdir} with
104 enough space to build and run all the tests.
105 Optional submit command @var{fate_recv} and a @var{comment} to describe
106 the testing profile are available.
107
108 Additional optional parameter to tune the Libav building and reporting process
109 can be passed.
110
111 @example
112 slot=                                   # some unique identifier
113 repo=git://git.libav.org/libav.git      # the source repository
114 samples=/path/to/fate/samples
115 workdir=                                # directory in which to do all the work
116 fate_recv="ssh -T fate@@fate.libav.org"  # command to submit report
117 comment=                                # optional description
118
119 # the following are optional and map to configure options
120 arch=
121 cpu=
122 cross_prefix=
123 cc=
124 target_os=
125 sysroot=
126 target_exec=
127 target_path=
128 extra_cflags=
129 extra_ldflags=
130 extra_libs=
131 extra_conf=     # extra configure options not covered above
132
133 #make=          # name of GNU make if not 'make'
134 makeopts=       # extra options passed to 'make'
135 #tar=           # command to create a tar archive from its arguments on
136                 # stdout, defaults to 'tar c'
137 @end example
138
139 @section Special Instances
140 The @var{TARGET_EXEC} option provides a way to run FATE wrapped in
141 @command{valgrind}, @command{qemu-user} or @command{wine} or on remote targets
142 through @command{ssh}.
143
144 @section Submitting Reports
145 In order to send reports you need to create an @command{ssh} key and send it
146 to @email{root@@libav.org}.
147 The current server fingerprint is @var{a4:99:d7:d3:1c:92:0d:56:d6:d5:61:be:01:ae:7d:e6}