doc/filters: add sepia example for colorchannelmixer
[ffmpeg.git] / doc / developer.texi
index fce842a..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.
-
-@end itemize
+@section Notes for external developers
 
-@section Integrating libavcodec or libavformat in your program
+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.
 
-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 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 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
 
@@ -147,29 +141,44 @@ GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}).
 @end itemize
 
 @subsection Naming conventions
-All names are using underscores (_), not CamelCase. For example, @samp{avfilter_get_video_buffer} is
-a valid function name and @samp{AVFilterGetVideo} is not. The exception from this are type names, like
+All names should be composed with underscores (_), not CamelCase. For example,
+@samp{avfilter_get_video_buffer} is an acceptable function name and
+@samp{AVFilterGetVideo} is not. The exception from this are type names, like
 for example structs and enums; they should always be in the CamelCase
 
-
-There are following conventions for naming variables and functions:
+There are the following conventions for naming variables and functions:
 @itemize @bullet
 @item
 For local variables no prefix is required.
 @item
-For variables and functions declared as @code{static} no prefixes are required.
+For file-scope variables and functions declared as @code{static}, no prefix
+is required.
 @item
-For variables and functions used internally by the library, @code{ff_} prefix
-should be used.
-For example, @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
-For exported names, each library has its own prefixes. Just check the existing
-code and name accordingly.
+Each library has its own prefix for public symbols, in addition to the
+commonly used @code{av_} (@code{avformat_} for libavformat,
+@code{avcodec_} for libavcodec, @code{swr_} for libswresample, etc).
+Check the existing code and choose names accordingly.
+Note that some symbols without these prefixes are also exported for
+retro-compatibility reasons. These exceptions are declared in the
+@code{lib<name>/lib<name>.v} files.
 @end itemize
 
+Furthermore, name space reserved for the system should not be invaded.
+Identifiers ending in @code{_t} are reserved by
+@url{http://pubs.opengroup.org/onlinepubs/007904975/functions/xsh_chap02_02.html#tag_02_02_02, POSIX}.
+Also avoid names starting with @code{__} or @code{_} followed by an uppercase
+letter as they are reserved by the C standard. Names starting with @code{_}
+are reserved at the file level and may not be used for externally visible
+symbols. If in doubt, just avoid names starting with @code{_} altogether.
+
 @subsection Miscellaneous conventions
 @itemize @bullet
 @item
@@ -191,7 +200,7 @@ set softtabstop=4
 set cindent
 set cinoptions=(0
 " Allow tabs in Makefiles.
-autocmd FileType make set noexpandtab shiftwidth=8 softtabstop=8
+autocmd FileType make,automake set noexpandtab shiftwidth=8 softtabstop=8
 " Trailing whitespace and tabs are forbidden, so highlight them.
 highlight ForbiddenWhitespace ctermbg=red guibg=red
 match ForbiddenWhitespace /\s\+$\|\t/
@@ -217,8 +226,13 @@ For Emacs, add these roughly equivalent lines to your @file{.emacs.d/init.el}:
 
 @enumerate
 @item
-   Contributions should be licensed under the LGPL 2.1, including an
-   "or any later version" clause, or the MIT license.  GPL 2 including
+   Contributions should be licensed under the
+   @uref{http://www.gnu.org/licenses/lgpl-2.1.html, LGPL 2.1},
+   including an "or any later version" clause, or, if you prefer
+   a gift-style license, the
+   @uref{http://www.isc.org/software/license/, ISC} or
+   @uref{http://mit-license.org/, MIT} license.
+   @uref{http://www.gnu.org/licenses/gpl-2.0.html, GPL 2} including
    an "or any later version" clause is also acceptable, but LGPL is
    preferred.
 @item
@@ -228,6 +242,13 @@ For Emacs, add these roughly equivalent lines to your @file{.emacs.d/init.el}:
    You can commit unfinished stuff (for testing etc), but it must be disabled
    (#ifdef etc) by default so it does not interfere with other developers'
    work.
+@item
+   The commit message should have a short first line in the form of
+   a @samp{topic: short description} as a header, separated by a newline
+   from the body consisting of an explanation of why the change is necessary.
+   If the commit fixes a known bug on the bug tracker, the commit message
+   should include its bug ID. Referring to the issue on the bug tracker does
+   not exempt you from writing an excerpt of the bug in the commit message.
 @item
    You do not have to over-test things. If it works for you, and you think it
    should work for others, then commit. If your code has problems
@@ -334,8 +355,6 @@ For Emacs, add these roughly equivalent lines to your @file{.emacs.d/init.el}:
 
 We think our rules are not too hard. If you have comments, contact us.
 
-Note, these rules are mostly borrowed from the MPlayer project.
-
 @anchor{Submitting patches}
 @section Submitting patches
 
@@ -500,6 +519,9 @@ send a reminder by email. Your patch should eventually be dealt with.
     Make sure you check the return values of function and return appropriate
     error codes. Especially memory allocation functions like @code{av_malloc()}
     are notoriously left unchecked, which is a serious problem.
+@item
+    Test your code with valgrind and or Address Sanitizer to ensure it's free
+    of leaks, out of array accesses, etc.
 @end enumerate
 
 @section Patch review process
@@ -552,4 +574,129 @@ 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
+
+FFmpeg maintains a set of @strong{release branches}, which are the
+recommended deliverable for system integrators and distributors (such as
+Linux distributions, etc.). At regular times, a @strong{release
+manager} prepares, tests and publishes tarballs on the
+@url{http://ffmpeg.org} website.
+
+There are two kinds of releases:
+
+@enumerate
+@item
+    @strong{Major releases} always include the latest and greatest
+    features and functionality.
+@item
+    @strong{Point releases} are cut from @strong{release} branches,
+    which are named @code{release/X}, with @code{X} being the release
+    version number.
+@end enumerate
+
+Note that we promise to our users that shared libraries from any FFmpeg
+release never break programs that have been @strong{compiled} against
+previous versions of @strong{the same release series} in any case!
+
+However, from time to time, we do make API changes that require adaptations
+in applications. Such changes are only allowed in (new) major releases and
+require further steps such as bumping library version numbers and/or
+adjustments to the symbol versioning file. Please discuss such changes
+on the @strong{ffmpeg-devel} mailing list in time to allow forward planning.
+
+@anchor{Criteria for Point Releases}
+@subsection Criteria for Point Releases
+
+Changes that match the following criteria are valid candidates for
+inclusion into a point release:
+
+@enumerate
+@item
+    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://trac.ffmpeg.org}.
+@item
+    Improves the included documentation.
+@item
+    Retains both source code and binary compatibility with previous
+    point releases of the same release branch.
+@end enumerate
+
+The order for checking the rules is (1 OR 2 OR 3) AND 4.
+
+
+@subsection Release Checklist
+
+The release process involves the following steps:
+
+@enumerate
+@item
+    Ensure that the @file{RELEASE} file contains the version number for
+    the upcoming release.
+@item
+    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
+    Make sure all relevant security fixes have been backported. See
+    @url{https://ffmpeg.org/security.html}.
+@item
+    Ensure that the FATE regression suite still passes in the release
+    branch on at least @strong{i386} and @strong{amd64}
+    (cf. @ref{Regression tests}).
+@item
+    Prepare the release tarballs in @code{bz2} and @code{gz} formats, and
+    supplementing files that contain @code{gpg} signatures
+@item
+    Publish the tarballs at @url{http://ffmpeg.org/releases}. Create and
+    push an annotated tag in the form @code{nX}, with @code{X}
+    containing the version number.
+@item
+    Propose and send a patch to the @strong{ffmpeg-devel} mailing list
+    with a news entry for the website.
+@item
+    Publish the news entry.
+@item
+    Send announcement to the mailing list.
+@end enumerate
+
 @bye