\input texinfo @c -*- texinfo -*-@documentencoding UTF-8 @settitle Developer Documentation@titlepage@center @titlefont{Developer Documentation}@end titlepage @top @contents @chapter Notes for external developers This document is mostly useful for internal FFmpeg developers.External developers who need to use the API in their application shouldrefer to the API doxygen documentation in the public headers, andcheck the examples in @file{doc/examples} and in the source code tosee how the public API is employed. You can use the FFmpeg libraries in your commercial program, but youare encouraged to @emph{publish any patch you make}. In this case thebest way to proceed is to send your patches to the ffmpeg-develmailing list following the guidelines illustrated in the remainder ofthis document. For more detailed legal information about the use of FFmpeg inexternal programs read the @file{LICENSE} file in the source tree andconsult @url{https://ffmpeg.org/legal.html}. @chapter Contributing There are 2 ways by which code gets into FFmpeg:@itemize @bullet@item Submitting patches to the ffmpeg-devel mailing list.      See @ref{Submitting patches} for details.@item Directly committing changes to the main tree.@end itemize Whichever way, changes should be reviewed by the maintainer of the codebefore they are committed. And they should follow the @ref{Coding Rules}.The developer making the commit and the author are responsible for their changesand should try to fix issues their commit causes. @anchor{Coding Rules}@chapter Coding Rules @section Code formatting conventions There are the following guidelines regarding the indentation in files: @itemize @bullet@itemIndent size is 4. @itemThe TAB character is forbidden outside of Makefiles as is anyform of trailing whitespace. Commits containing either will berejected by the git repository. @itemYou should try to limit your code lines to 80 characters; however, do so ifand only if this improves readability. @itemK&R coding style is used.@end itemizeThe presentation is one inspired by 'indent -i4 -kr -nut'. The main priority in FFmpeg is simplicity and small code size in order tominimize the bug count. @section CommentsUse the JavaDoc/Doxygen  format (see examples below) so that code documentationcan be generated automatically. All nontrivial functions should have a commentabove 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 employedfor markup commands, i.e. use @code{@@param} and not @code{\param}. @example/** * @@file * MPEG codec. * @@author ... */ /** * Summary sentence. * more text ... * ... */typedef struct Foobar @{    int var1; /**< var1 description */    int var2; ///< var2 description    /** var3 description */    int var3;@} Foobar; /** * Summary sentence. * more text ... * ... * @@param my_parameter description of my_parameter * @@return return value description */int myfunc(int my_parameter)...@end example @section C language features FFmpeg is programmed in the ISO C90 language with a few additionalfeatures from ISO C99, namely: @itemize @bullet@itemthe @samp{inline} keyword; @item@samp{//} comments; @itemdesignated struct initializers (@samp{struct s x = @{ .i = 17 @};}); @itemcompound literals (@samp{x = (struct s) @{ 17, 23 @};}). @itemfor loops with variable definition (@samp{for (int i = 0; i < 8; i++)}); @itemVariadic macros (@samp{#define ARRAY(nb, ...) (int[nb + 1])@{ nb, __VA_ARGS__ @}}); @itemImplementation defined behavior for signed integers is assumed to match theexpected behavior for two's complement. Non representable values in integercasts are binary truncated. Shift right of signed values uses sign extension.@end itemize These features are supported by all compilers we care about, so we will notaccept patches to remove their use unless they absolutely do not impairclarity and performance. All code must compile with recent versions of GCC and a number of othercurrently supported compilers. To ensure compatibility, please do not useadditional C99 features or GCC extensions. Especially watch out for: @itemize @bullet@itemmixing statements and declarations; @item@samp{long long} (use @samp{int64_t} instead); @item@samp{__attribute__} not protected by @samp{#ifdef __GNUC__} or similar; @itemGCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}).@end itemize @section Naming conventionsAll 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, likefor example structs and enums; they should always be in CamelCase. There are the following conventions for naming variables and functions: @itemize @bullet@itemFor local variables no prefix is required. @itemFor file-scope variables and functions declared as @code{static}, no prefixis required. @itemFor variables and functions visible outside of file scope, but only usedinternally by a library, an @code{ff_} prefix should be used,e.g. @samp{ff_w64_demuxer}. @itemFor variables and functions visible outside of file scope, used internallyacross multiple libraries, use @code{avpriv_} as prefix, for example,@samp{avpriv_report_missing_feature}. @itemEach library has its own prefix for public symbols, in addition to thecommonly 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 forretro-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 uppercaseletter 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 visiblesymbols. If in doubt, just avoid names starting with @code{_} altogether. @section Miscellaneous conventions @itemize @bullet@itemfprintf and printf are forbidden in libavformat and libavcodec,please use av_log() instead. @itemCasts should be used only when necessary. Unneeded parenthesesshould also be avoided if they don't make the code easier to understand.@end itemize @section Editor configurationIn order to configure Vim to follow FFmpeg formatting conventions, pastethe following snippet into your @file{.vimrc}:@example" indentation rules for FFmpeg: 4 spaces, no tabsset expandtabset shiftwidth=4set softtabstop=4set cindentset cinoptions=(0" Allow tabs in Makefiles.autocmd FileType make,automake set noexpandtab shiftwidth=8 softtabstop=8" Trailing whitespace and tabs are forbidden, so highlight them.highlight ForbiddenWhitespace ctermbg=red guibg=redmatch 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}:@lisp(c-add-style "ffmpeg"             '("k&r"               (c-basic-offset . 4)               (indent-tabs-mode . nil)               (show-trailing-whitespace . t)               (c-offsets-alist                (statement-cont . (c-lineup-assignments +)))               )             )(setq c-default-style "ffmpeg")@end lisp @chapter Development Policy @section Patches/Committing@subheading Licenses for patches must be compatible with FFmpeg.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 prefera gift-style license, the@uref{http://opensource.org/licenses/isc-license.txt, ISC} or@uref{http://mit-license.org/, MIT} license.@uref{http://www.gnu.org/licenses/gpl-2.0.html, GPL 2} includingan "or any later version" clause is also acceptable, but LGPL ispreferred.If you add a new file, give it a proper license header. Do not copy andpaste it from a random place, use an existing file as template. @subheading You must not commit code which breaks FFmpeg!This means unfinished code which is enabled and breaks compilation,or compiles but does not work/breaks the regression tests. Code whichis unfinished but disabled may be permitted under-circumstances, likemissing samples or an implementation with a small subset of features.Always check the mailing list for any reviewers with issues and testFATE before you push. @subheading Keep the main commit message short with an extended description below.The commit message should have a short first line in the form ofa @samp{topic: short description} as a header, separated by a newlinefrom 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 messageshould include its bug ID. Referring to the issue on the bug tracker doesnot exempt you from writing an excerpt of the bug in the commit message. @subheading Testing must be adequate but not excessive.If it works for you, others, and passes FATE then it should be OK to commitit, provided it fits the other committing criteria. You should not worry aboutover-testing things. If your code has problems (portability, triggerscompiler bugs, unusual environment etc) they will be reported and eventuallyfixed. @subheading Do not commit unrelated changes together.They should be split them into self-contained pieces. Also do not forgetthat if part B depends on part A, but A does not depend on B, then A canand should be committed first and separate from B. Keeping changes wellsplit into self-contained parts makes reviewing and understanding them onthe commit log mailing list easier. This also helps in case of debugginglater on.Also if you have doubts about splitting or not splitting, do not hesitate toask/discuss it on the developer mailing list. @subheading Ask before you change the build system (configure, etc).Do not commit changes to the build system (Makefiles, configure script)which change behavior, defaults etc, without asking first. The sameapplies to compiler warning fixes, trivial looking fixes and to codemaintained by other developers. We usually have a reason for doing thingsthe way we do. Send your changes as patches to the ffmpeg-devel mailinglist, and if the code maintainers say OK, you may commit. This does notapply to files you wrote and/or maintain. @subheading Cosmetic changes should be kept in separate patches.We refuse source indentation and other cosmetic changes if they are mixedwith functional changes, such commits will be rejected and removed. Everydeveloper has his own indentation style, you should not change it. Of courseif you (re)write something, you can use your own style, even though we wouldprefer if the indentation throughout FFmpeg was consistent (Many projectsforce a given indentation style - we do not.). If you really need to makeindentation changes (try to avoid this), separate them strictly from realchanges. NOTE: If you had to put if()@{ .. @} over a large (> 5 lines) chunk of code,then either do NOT change the indentation of the inner part within (do notmove it to the right)! or do so in a separate commit @subheading Commit messages should always be filled out properly.Always fill out the commit log message. Describe in a few lines what youchanged and why. You can refer to mailing list postings if you fix aparticular bug. Comments such as "fixed!" or "Changed it." are unacceptable.Recommended format: @examplearea changed: Short 1 line description details describing what and why and giving references.@end example @subheading Credit the author of the patch.Make sure the author of the commit is set correctly. (see git commit --author)If you apply a patch, send ananswer to ffmpeg-devel (or wherever you got the patch from) saying thatyou applied the patch. @subheading Complex patches should refer to discussion surrounding them.When applying patches that have been discussed (at length) on the mailinglist, reference the thread in the log message. @subheading Always wait long enough before pushing changesDo NOT commit to code actively maintained by others without permission.Send a patch to ffmpeg-devel. If no one answers within a reasonabletime-frame (12h for build failures and security fixes, 3 days small changes,1 week for big patches) then commit your patch if you think it is OK.Also note, the maintainer can simply ask for more time to review! @section Code@subheading API/ABI changes should be discussed before they are made.Do not change behavior of the programs (renaming options etc) or publicAPI or ABI without first discussing it on the ffmpeg-devel mailing list.Do not remove widely used functionality or features (redundant code can be removed). @subheading Remember to check if you need to bump versions for libav*.Depending on the change, you may need to change the version integer.Incrementing the first component means no backward compatibility toprevious versions (e.g. removal of a function from the public API).Incrementing the second component means backward compatible change(e.g. addition of a function to the public API or extension of anexisting data structure).Incrementing the third component means a noteworthy binary compatiblechange (e.g. encoder bug fix that matters for the decoder). The thirdcomponent always starts at 100 to distinguish FFmpeg from Libav. @subheading Warnings for correct code may be disabled if there is no other option.Compiler warnings indicate potential bugs or code with bad style. If a type ofwarning always points to correct and clean code, that warning shouldbe disabled, not the code changed.Thus the remaining warnings can either be bugs or correct code.If it is a bug, the bug has to be fixed. If it is not, the code shouldbe changed to not generate a warning unless that causes a slowdownor obfuscates the code. @subheading Check untrusted input properly.Never write to unallocated memory, never write over the end of arrays,always check values read from some untrusted source before using themas array index or other risky things. @section Documentation/Other@subheading Subscribe to the ffmpeg-devel mailing list.It is important to be subscribed to the@uref{https://lists.ffmpeg.org/mailman/listinfo/ffmpeg-devel, ffmpeg-devel}mailing list. Almost any non-trivial patch is to be sent there for review.Other developers may have comments about your contribution. We expect you seethose comments, and to improve it if requested. (N.B. Experienced committershave other channels, and may sometimes skip review for trivial fixes.) Also,discussion here about bug fixes and FFmpeg improvements by other developers maybe helpful information for you. Finally, by being a list subscriber, yourcontribution will be posted immediately to the list, without the moderationhold which messages from non-subscribers experience. However, it is more important to the project that we receive your patch thanthat you be subscribed to the ffmpeg-devel list. If you have a patch, and don'twant to subscribe and discuss the patch, then please do send it to the listanyway. @subheading Subscribe to the ffmpeg-cvslog mailing list.Diffs of all commits are sent to the@uref{https://lists.ffmpeg.org/mailman/listinfo/ffmpeg-cvslog, ffmpeg-cvslog}mailing list. Some developers read this list to review all code base changesfrom all sources. Subscribing to this list is not mandatory. @subheading Keep the documentation up to date.Update the documentation if you change behavior or add features. If you areunsure how best to do this, send a patch to ffmpeg-devel, the documentationmaintainer(s) will review and commit your stuff. @subheading Important discussions should be accessible to all.Try to keep important discussions and requests (also) on the publicdeveloper mailing list, so that all developers can benefit from them. @subheading Check your entries in MAINTAINERS.Make sure that no parts of the codebase that you maintain are missing from the@file{MAINTAINERS} file. If something that you want to maintain is missing add it withyour name after it.If at some point you no longer want to maintain some code, then please help infinding a new maintainer and also don't forget to update the @file{MAINTAINERS} file. We think our rules are not too hard. If you have comments, contact us. @chapter Code of conduct Be friendly and respectful towards others and third parties.Treat others the way you yourself want to be treated. Be considerate. Not everyone shares the same viewpoint and priorities as you do.Different opinions and interpretations help the project.Looking at issues from a different perspective assists development. Do not assume malice for things that can be attributed to incompetence. Even ifit is malice, it's rarely good to start with that as initial assumption. Stay friendly even if someone acts contrarily. Everyone has a bad dayonce in a while.If you yourself have a bad day or are angry then try to take a break and replyonce you are calm and without anger if you have to. Try to help other team members and cooperate if you can. The goal of software development is to create technical excellence, not for anyindividual to be better and "win" against the others. Large software projectsare only possible and successful through teamwork. If someone struggles do not put them down. Give them a helping handinstead and point them in the right direction. Finally, keep in mind the immortal words of Bill and Ted,"Be excellent to each other." @anchor{Submitting patches}@chapter Submitting patches First, read the @ref{Coding Rules} above if you did not yet, in particularthe rules regarding patch submission. When you submit your patch, please use @code{git format-patch} or@code{git send-email}. We cannot read other diffs :-). Also please do not submit a patch which contains several unrelated changes.Split it into separate, self-contained pieces. This does not mean splittingfile by file. Instead, make the patch as small as possible while stillkeeping it as a logical unit that contains an individual change, evenif it spans multiple files. This makes reviewing your patches much easierfor us and greatly increases your chances of getting your patch applied. Use the patcheck tool of FFmpeg to check your patch.The tool is located in the tools directory. Run the @ref{Regression tests} before submitting a patch in order to verifyit does not cause unexpected problems. 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 compliantand has no lrint()') Also please if you send several patches, send each patch as a separate mail,do not attach several unrelated patches to the same mail. Patches should be posted to the@uref{https://lists.ffmpeg.org/mailman/listinfo/ffmpeg-devel, ffmpeg-devel}mailing list. Use @code{git send-email} when possible since it will properlysend patches without requiring extra care. If you cannot, then send patchesas base64-encoded attachments, so your patch is not trashed duringtransmission. Also ensure the correct mime type is used(text/x-diff or text/x-patch or at least text/plain) and that only onepatch is inline or attached per mail.You can check @url{https://patchwork.ffmpeg.org}, if your patch does not show up, its mime typelikely was wrong. Your patch will be reviewed on the mailing list. You will likely be askedto make some changes and are expected to send in an improved version thatincorporates the requests from the review. This process may go throughseveral iterations. Once your patch is deemed good enough, some developer

Lines 1–500 of 866. Load more