doc: update build system documentation
authorLuca Barbato <lu_zero@gentoo.org>
Mon, 21 Mar 2011 23:20:56 +0000 (00:20 +0100)
committerLuca Barbato <lu_zero@gentoo.org>
Fri, 25 Mar 2011 08:48:25 +0000 (09:48 +0100)
Split normal build system documentation and the fate one.

Document THREADS make variable and provide an introduction to fate.
Document DESTDIR make variable and add some generic targets.

doc/build_system.txt
doc/fate.txt [new file with mode: 0644]

index 5a59f35..1011f57 100644 (file)
@@ -1,37 +1,30 @@
 Libav currently uses a custom build system, this text attempts to document
 some of its obscure features and options.
 
-Options to make:
-make V=1 <target>
-    Build target with verbosity 1, instead of 1, 2 can be used too
-make SAMPLES=<path to the fate samples> <target>
-    specify the path to the fate samples at make time
+Makefile variables:
 
+V
+    Disable the default terse mode, the full command issued by make and its
+    output will be shown on the screen.
 
-Useful standard make commands:
-make -t <target>
-    Touch all files that otherwise would be build, this is useful to reduce
-    unneeded rebuilding when changing headers, but note you must force rebuilds
-    of files that actually need it by hand then.
+DESTDIR
+    Destination directory for the install targets, useful to prepare packages
+    or install Libav in cross-environments.
 
-make -j<num>
-    rebuild with multiple jobs at the same time. Faster on multi processor systems
+Makefile targets:
 
-make -k
-    continue build in case of errors, this is useful for the regression tests
-    sometimes but note it will still not run all reg tests.
+all
+    Default target, builds all the libraries and the executables.
 
+install
+    Install headers, libraries and programs.
 
-Targets to make:
-fate-list
-    Will list all fate/regression test targets
+libavformat/output-example
+    Build the libavformat basic example.
 
-fate
-    Run the fate test suite, note you must have installed it
+libavcodec/api-example
+    Build the libavcodec basic example.
 
+libswscale/swscale-test
+    Build the swscale self-test (useful also as example).
 
-Setting up local fate:
-use the following command to get the fate test samples
-rsync -aL rsync://rsync.mplayerhq.hu:/samples/fate-suite/ fate/fate-suite
-pass --samples=<path to the samples> to configure or pass the path with the
-SAMPLES variable to make
diff --git a/doc/fate.txt b/doc/fate.txt
new file mode 100644 (file)
index 0000000..f5f3759
--- /dev/null
@@ -0,0 +1,45 @@
+FATE Automated Testing Environment
+
+FATE provides a regression testsuite that can be run locally or configured
+to send reports to fate.libav.org.
+In order to run, it needs a large amount of data (samples and references)
+that is provided separately from the actual source distribution.
+
+Use the following command to get the fate test samples
+
+# rsync -aL rsync://samples.libav.org:/samples/fate-suite/ fate-suite
+
+To inform the build system about the testsuite location, pass
+`--samples=<path to the samples>` to configure or set the SAMPLES Make
+variable or the FATE_SAMPLES environment variable to a suitable value.
+
+For information on how to set up FATE to send results to the official Libav
+testing framework, please refer to the following wiki page:
+http://wiki.multimedia.cx/index.php?title=FATE
+
+FATE Makefile targets:
+
+fate-list
+    Will list all fate/regression test targets.
+
+fate
+    Run the FATE test suite (requires the fate-suite dataset).
+
+Fate Makefile variables:
+
+V
+    Verbosity level, can be set to 0, 1 or 2.
+    * 0: show just the test arguments
+    * 1: show just the command used in the test
+    * 2: show everything
+
+SAMPLES
+    Specify or override the path to the FATE samples at make time, it has a
+    meaning only while running the regression tests.
+
+THREADS
+    Specify how many threads to use while running regression tests, it is
+    quite useful to detect thread-related regressions.
+
+Example:
+    make V=1 SAMPLES=/var/fate/samples THREADS=2 fate