doc/filters: add sepia example for colorchannelmixer
[ffmpeg.git] / doc / developer.texi
index bd3f7a7..af7e7de 100644 (file)
 
 @chapter Developers Guide
 
-@section API
-@itemize @bullet
-@item libavcodec is the library containing the codecs (both encoding and
-decoding). Look at @file{doc/examples/decoding_encoding.c} to see how to use
-it.
-
-@item libavformat is the library containing the file format handling (mux and
-demux code for several formats). Look at @file{ffplay.c} to use it in a
-player. See @file{doc/examples/muxing.c} to use it to generate audio or video
-streams.
+@section Notes for external developers
 
-@end itemize
+This document is mostly useful for internal FFmpeg developers.
+External developers who need to use the API in their application should
+refer to the API doxygen documentation in the public headers, and
+check the examples in @file{doc/examples} and in the source code to
+see how the public API is employed.
 
-@section Integrating libavcodec or libavformat in your program
+You can use the FFmpeg libraries in your commercial program, but you
+are encouraged to @emph{publish any patch you make}. In this case the
+best way to proceed is to send your patches to the ffmpeg-devel
+mailing list following the guidelines illustrated in the remainder of
+this document.
 
-You can integrate all the source code of the libraries to link them
-statically to avoid any version problem. All you need is to provide a
-'config.mak' and a 'config.h' in the parent directory. See the defines
-generated by ./configure to understand what is needed.
-
-You can use libavcodec or libavformat in your commercial program, but
-@emph{any patch you make must be published}. The best way to proceed is
-to send your patches to the FFmpeg mailing list.
+For more detailed legal information about the use of FFmpeg in
+external programs read the @file{LICENSE} file in the source tree and
+consult @url{http://ffmpeg.org/legal.html}.
 
 @section Contributing
 
@@ -157,13 +151,16 @@ There are the following conventions for naming variables and functions:
 @item
 For local variables no prefix is required.
 @item
-For variables and functions declared as @code{static} no prefix is required.
+For file-scope variables and functions declared as @code{static}, no prefix
+is required.
 @item
-For variables and functions used internally by a library an @code{ff_}
-prefix should be used, e.g. @samp{ff_w64_demuxer}.
+For variables and functions visible outside of file scope, but only used
+internally by a library, an @code{ff_} prefix should be used,
+e.g. @samp{ff_w64_demuxer}.
 @item
-For variables and functions used internally across multiple libraries, use
-@code{avpriv_}. For example, @samp{avpriv_aac_parse_header}.
+For variables and functions visible outside of file scope, used internally
+across multiple libraries, use @code{avpriv_} as prefix, for example,
+@samp{avpriv_aac_parse_header}.
 @item
 Each library has its own prefix for public symbols, in addition to the
 commonly used @code{av_} (@code{avformat_} for libavformat,
@@ -577,6 +574,43 @@ message or introductionary message for the patch series that you post to
 the ffmpeg-devel mailing list, a direct link to download the sample media.
 
 
+@subsection Visualizing Test Coverage
+
+The FFmpeg build system allows visualizing the test coverage in an easy
+manner with the coverage tools @code{gcov}/@code{lcov}.  This involves
+the following steps:
+
+@enumerate
+@item
+    Configure to compile with instrumentation enabled:
+    @code{configure --toolchain=gcov}.
+@item
+    Run your test case, either manually or via FATE. This can be either
+    the full FATE regression suite, or any arbitrary invocation of any
+    front-end tool provided by FFmpeg, in any combination.
+@item
+    Run @code{make lcov} to generate coverage data in HTML format.
+@item
+    View @code{lcov/index.html} in your preferred HTML viewer.
+@end enumerate
+
+You can use the command @code{make lcov-reset} to reset the coverage
+measurements. You will need to rerun @code{make lcov} after running a
+new test.
+
+@subsection Using Valgrind
+
+The configure script provides a shortcut for using valgrind to spot bugs
+related to memory handling. Just add the option
+@code{--toolchain=valgrind-memcheck} or @code{--toolchain=valgrind-massif}
+to your configure line, and reasonable defaults will be set for running
+FATE under the supervision of either the @strong{memcheck} or the
+@strong{massif} tool of the valgrind suite.
+
+In case you need finer control over how valgrind is invoked, use the
+@code{--target-exec='valgrind <your_custom_valgrind_options>} option in
+your configure line instead.
+
 @anchor{Release process}
 @section Release process
 
@@ -619,7 +653,7 @@ inclusion into a point release:
     Fixes a security issue, preferably identified by a @strong{CVE
     number} issued by @url{http://cve.mitre.org/}.
 @item
-    Fixes a documented bug in @url{https://ffmpeg.org/trac/ffmpeg}.
+    Fixes a documented bug in @url{https://trac.ffmpeg.org}.
 @item
     Improves the included documentation.
 @item
@@ -639,7 +673,7 @@ The release process involves the following steps:
     Ensure that the @file{RELEASE} file contains the version number for
     the upcoming release.
 @item
-    Add the release at @url{https://ffmpeg.org/trac/ffmpeg/admin/ticket/versions}.
+    Add the release at @url{https://trac.ffmpeg.org/admin/ticket/versions}.
 @item
     Announce the intent to do a release to the mailing list.
 @item