decoding). Look at @file{libavcodec/apiexample.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
+demux code for several formats). Look at @file{avplay.c} to use it in a
player. See @file{libavformat/output-example.c} to use it to generate
audio or video streams.
You can use Libav in your commercial program, but you must abide to the
license, LGPL or GPL depending on the specific features used, please refer
-to @url{http://libav.org/legal.html} for a quick checklist and to
-@url{http://git.libav.org/?p=libav.git;a=blob;f=COPYING.GPLv2},
-@url{http://git.libav.org/?p=libav.git;a=blob;f=COPYING.GPLv3},
-@url{http://git.libav.org/?p=libav.git;a=blob;f=COPYING.LGPLv2.1},
-@url{http://git.libav.org/?p=libav.git;a=blob;f=COPYING.LGPLv3} for the
-exact text of the licenses.
+to @uref{http://libav.org/legal.html, our legal page} for a quick checklist and to
+the following links for the exact text of each license:
+@uref{http://git.libav.org/?p=libav.git;a=blob;f=COPYING.GPLv2, GPL version 2},
+@uref{http://git.libav.org/?p=libav.git;a=blob;f=COPYING.GPLv3, GPL version 3},
+@uref{http://git.libav.org/?p=libav.git;a=blob;f=COPYING.LGPLv2.1, LGPL version 2.1},
+@uref{http://git.libav.org/?p=libav.git;a=blob;f=COPYING.LGPLv3, LGPL version 3}.
Any modification to the source code can be suggested for inclusion.
-The best way to proceed is to send your patches to the Libav mailing list.
+The best way to proceed is to send your patches to the
+@uref{https://lists.libav.org/mailman/listinfo/libav-devel, libav-devel}
+mailing list.
@anchor{Coding Rules}
@section Coding Rules
-Libav is programmed in the ISO C90 language with a few additional
-features from ISO C99, namely:
+@subsection Code formatting conventions
+The code is written in K&R C style. That means the following:
@itemize @bullet
@item
-the @samp{inline} keyword;
+The control statements are formatted by putting space between the statement
+and parenthesis in the following way:
+@example
+for (i = 0; i < filter->input_count; i++) @{
+@end example
@item
-@samp{//} comments;
+The case statement is always located at the same level as the switch itself:
+@example
+switch (link->init_state) @{
+case AVLINK_INIT:
+ continue;
+case AVLINK_STARTINIT:
+ av_log(filter, AV_LOG_INFO, "circular filter chain detected");
+ return 0;
+@end example
@item
-designated struct initializers (@samp{struct s x = @{ .i = 17 @};})
+Braces in function declarations are written on the new line:
+@example
+const char *avfilter_configuration(void)
+@{
+ return LIBAV_CONFIGURATION;
+@}
+@end example
@item
-compound literals (@samp{x = (struct s) @{ 17, 23 @};})
+In case of a single-statement if, no curly braces are required:
+@example
+if (!pic || !picref)
+ goto fail;
+@end example
+@item
+Do not put spaces immediately inside parentheses. @samp{if (ret)} is
+a valid style; @samp{if ( ret )} is not.
@end itemize
-These features are supported by all compilers we care about, so we will not
-accept patches to remove their use unless they absolutely do not impair
-clarity and performance.
-
-All code must compile with GCC 2.95 and GCC 3.3. Currently, Libav also
-compiles with several other compilers, such as the Compaq ccc compiler
-or Sun Studio 9, and we would like to keep it that way unless it would
-be exceedingly involved. To ensure compatibility, please do not use any
-additional C99 features or GCC extensions. Especially watch out for:
+There are the following guidelines regarding the indentation in files:
@itemize @bullet
@item
-mixing statements and declarations;
-@item
-@samp{long long} (use @samp{int64_t} instead);
-@item
-@samp{__attribute__} not protected by @samp{#ifdef __GNUC__} or similar;
-@item
-GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}).
-@end itemize
-
Indent size is 4.
-The presentation is one inspired by 'indent -i4 -kr -nut'.
+@item
The TAB character is forbidden outside of Makefiles as is any
form of trailing whitespace. Commits containing either will be
rejected by the git repository.
+@item
+You should try to limit your code lines to 80 characters; however, do so if
+and only if this improves readability.
+@end itemize
+The presentation is one inspired by 'indent -i4 -kr -nut'.
The main priority in Libav is simplicity and small code size in order to
minimize the bug count.
-Comments: Use the JavaDoc/Doxygen
-format (see examples below) so that code documentation
+@subsection Comments
+Use the JavaDoc/Doxygen format (see examples below) so that code documentation
can be generated automatically. All nontrivial functions should have a comment
above them explaining what the function does, even if it is just one sentence.
All structures and their member variables should be documented, too.
+
+Avoid Qt-style and similar Doxygen syntax with @code{!} in it, i.e. replace
+@code{//!} with @code{///} and similar. Also @@ syntax should be employed
+for markup commands, i.e. use @code{@@param} and not @code{\param}.
+
@example
/**
- * @@file mpeg.c
+ * @@file
* MPEG codec.
* @@author ...
*/
...
@end example
+@subsection C language features
+
+Libav is programmed in the ISO C90 language with a few additional
+features from ISO C99, namely:
+@itemize @bullet
+@item
+the @samp{inline} keyword;
+@item
+@samp{//} comments;
+@item
+designated struct initializers (@samp{struct s x = @{ .i = 17 @};})
+@item
+compound literals (@samp{x = (struct s) @{ 17, 23 @};})
+@end itemize
+
+These features are supported by all compilers we care about, so we will not
+accept patches to remove their use unless they absolutely do not impair
+clarity and performance.
+
+All code must compile with recent versions of GCC and a number of other
+currently supported compilers. To ensure compatibility, please do not use
+additional C99 features or GCC extensions. Especially watch out for:
+@itemize @bullet
+@item
+mixing statements and declarations;
+@item
+@samp{long long} (use @samp{int64_t} instead);
+@item
+@samp{__attribute__} not protected by @samp{#ifdef __GNUC__} or similar;
+@item
+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 only exception from this are structure
+names; they should always be in the CamelCase
+
+There are 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.
+@item
+For variables and functions used internally by the library, @code{ff_} prefix
+should be used.
+For example, @samp{ff_w64_demuxer}.
+@item
+For variables and functions used internally across multiple libraries, use
+@code{avpriv_}. 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.
+@end itemize
+
+@subsection Miscellanous conventions
+@itemize @bullet
+@item
fprintf and printf are forbidden in libavformat and libavcodec,
please use av_log() instead.
-
+@item
Casts should be used only when necessary. Unneeded parentheses
should also be avoided if they don't make the code easier to understand.
+@end itemize
+
+@subsection Editor configuration
+In order to configure Vim to follow Libav formatting conventions, paste
+the following snippet into your @file{.vimrc}:
+@example
+" indentation rules for libav: 4 spaces, no tabs
+set expandtab
+set shiftwidth=4
+set softtabstop=4
+" allow tabs in Makefiles
+autocmd FileType make 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/
+" Do not highlight spaces at the end of line while typing on that line.
+autocmd InsertEnter * match ForbiddenWhitespace /\t\|\s\+\%#\@@<!$/
+@end example
+
+For Emacs, add these roughly equivalent lines to your @file{.emacs.d/init.el}:
+@example
+(setq c-default-style "k&r")
+(setq-default c-basic-offset 4)
+(setq-default indent-tabs-mode nil)
+(setq-default show-trailing-whitespace t)
+@end example
@section Development Policy
When applying patches that have been discussed (at length) on the mailing
list, reference the thread in the log message.
@item
- Subscribe to the libav-devel and libav-commits mailing list.
+ Subscribe to the
+ @uref{https://lists.libav.org/mailman/listinfo/libav-devel, libav-devel} and
+ @uref{https://lists.libav.org/mailman/listinfo/libav-commits, libav-commits}
+ mailing lists.
Bugs and possible improvements or general questions regarding commits
are discussed on libav-devel. We expect you to react if problems with
your code are uncovered.
@section Submitting patches
-First, read the (@pxref{Coding Rules}) above if you did not yet, in particular
+First, read the @ref{Coding Rules} above if you did not yet, in particular
the rules regarding patch submission.
As stated already, please do not submit a patch which contains several
Use the patcheck tool of Libav to check your patch.
The tool is located in the tools directory.
-Run the @pxref{Regression Tests} before submitting a patch in order to verify
+Run the @ref{Regression Tests} before submitting a patch in order to verify
it does not cause unexpected problems.
Patches should be posted as base64 encoded attachments (or any other
encoding which ensures that the patch will not be trashed during
-transmission) to the libav-devel mailing list, see
-@url{https://lists.libav.org/mailman/listinfo/libav-devel}
+transmission) to the
+@uref{https://lists.libav.org/mailman/listinfo/libav-devel, libav-devel}
+mailing list.
It also helps quite a bit if you tell us what the patch does (for example
'replaces lrint by lrintf'), and why (for example '*BSD isn't C99 compliant
AVInputFormat/AVOutputFormat struct?
@item
Did you bump the minor version number (and reset the micro version
- number) in @file{avcodec.h} or @file{avformat.h}?
+ number) in @file{libavcodec/version.h} or @file{libavformat/version.h}?
@item
Did you register it in @file{allcodecs.c} or @file{allformats.c}?
@item
configure?
@item
Did you @code{git add} the appropriate files before committing?
+@item
+ Did you make sure it compiles standalone, i.e. with
+ @code{configure --disable-everything --enable-decoder=foo}
+ (or @code{--enable-demuxer} or whatever your component is)?
@end enumerate
+
@section patch submission checklist
@enumerate
@item
- Do the regression tests pass with the patch applied?
+ Does @code{make fate} pass with the patch applied?
@item
Does @code{make checkheaders} pass with the patch applied?
@item
Is the patch against latest Libav git master branch?
@item
- Are you subscribed to libav-devel?
- (@url{https://lists.libav.org/mailman/listinfo/libav-devel}
- the list is subscribers)
+ Are you subscribed to the
+ @uref{https://lists.libav.org/mailman/listinfo/libav-devel, libav-devel}
+ mailing list? (Only list subscribers are allowed to post.)
@item
Have you checked that the changes are minimal, so that the same cannot be
achieved with a smaller patch and/or simpler final code?
@section Patch review process
-All patches posted to libav-devel will be reviewed, unless they contain a
+All patches posted to the
+@uref{https://lists.libav.org/mailman/listinfo/libav-devel, libav-devel}
+mailing list will be reviewed, unless they contain a
clear note that the patch is not for the git master branch.
Reviews and comments will be posted as replies to the patch on the
mailing list. The patch submitter then has to take care of every comment,
to commit the update reference with the change and to explain in the comment
why the expected result changed.
-Please refer to @file{doc/fate.txt}.
+Please refer to @url{fate.html}.
@bye
projects / ffmpeg / blobdiff