doc: Document FATE option HWACCEL
[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 test suite 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 test suite 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
55 @table @option
56 @item fate-list
57 List all fate/regression test targets.
58
59 @item fate-rsync
60 Shortcut to download the fate test samples to the specified test suite location.
61
62 @item fate
63 Run the FATE test suite (requires the fate-suite dataset).
64 @end table
65
66 @section FATE Makefile variables
67 @table @option
68 @item V
69 Verbosity level, can be set to 0, 1 or 2.
70
71 @table @option
72 @item 0
73 show just the test arguments
74
75 @item 1
76 show just the command used in the test
77
78 @item 2
79 show everything
80 @end table
81
82 @item SAMPLES
83 Specify or override the path to the FATE samples at make time, it has a
84 meaning only while running the regression tests.
85
86 @item THREADS
87 Specify how many threads to use while running regression tests, it is
88 quite useful to detect thread-related regressions.
89
90 @item THREAD_TYPE
91 Specify which threading strategy test, either @var{slice} or @var{frame},
92 by default @var{slice+frame}
93
94 @item CPUFLAGS
95 Specify a mask to be applied to autodetected CPU flags.
96
97 @item TARGET_EXEC
98 Specify or override the wrapper used to run the tests.
99
100 @item GEN
101 Set to @var{1} to generate the missing or mismatched references.
102
103 @item HWACCEL
104 Specify which hardware acceleration to use while running regression tests,
105 by default none is used.
106
107 @end table
108
109 @example
110     make V=1 SAMPLES=/var/fate/samples THREADS=2 CPUFLAGS=mmx fate
111 @end example
112
113 @chapter Automated Tests
114 In order to automatically testing specific configurations, e.g. multiple
115 compilers, @command{tests/fate.sh} is provided.
116
117 This shell script builds Libav, runs the regression tests and prepares
118 a report that can be sent to @url{http://fate.libav.org/} or directly
119 examined locally.
120
121 @section Testing Profiles
122 The configuration file passed to @command{fate.sh} is shell scripts as well.
123
124 It must provide at least a @var{slot} identifier, the @var{repo} from
125 which fetch the sources, the @var{samples} directory, a @var{workdir} with
126 enough space to build and run all the tests.
127 Optional submit command @var{fate_recv} and a @var{comment} to describe
128 the testing profile are available.
129
130 Additional optional parameter to tune the Libav building and reporting process
131 can be passed.
132
133 @example
134 slot=                                   # some unique identifier
135 repo=git://git.libav.org/libav.git      # the source repository
136 #branch=release/10                      # the branch to test
137 samples=/path/to/fate/samples
138 workdir=                                # directory in which to do all the work
139 fate_recv="ssh -T fate@@fate.libav.org"  # command to submit report
140 comment=                                # optional description
141 build_only=     # set to "yes" for a compile-only instance that skips tests
142
143 # the following are optional and map to configure options
144 arch=
145 cpu=
146 cross_prefix=
147 as=
148 cc=
149 ld=
150 target_os=
151 sysroot=
152 target_exec=
153 target_path=
154 target_samples=
155 extra_cflags=
156 extra_ldflags=
157 extra_libs=
158 extra_conf=     # extra configure options not covered above
159
160 #make=          # name of GNU make if not 'make'
161 makeopts=       # extra options passed to 'make'
162 #tar=           # command to create a tar archive from its arguments on
163                 # stdout, defaults to 'tar c'
164 @end example
165
166 @section Special Instances
167 The @var{TARGET_EXEC} option provides a way to run FATE wrapped in
168 @command{valgrind}, @command{qemu-user} or @command{wine} or on remote targets
169 through @command{ssh}.
170
171 @section Submitting Reports
172 In order to send reports you need to create an @command{ssh} key and send it
173 to @email{root@@libav.org}.