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.
@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 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:
+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
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
@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
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