This is an automated email from the git hooks/post-receive script. Git pushed a commit to branch master in repository ffmpeg.
commit 7fa951d330bdb2237816f0622eb46165da9714df Author: Romain Beauxis <[email protected]> AuthorDate: Thu Nov 5 10:03:50 2026 -0600 Commit: Romain Beauxis <[email protected]> CommitDate: Thu Nov 12 16:49:31 2026 +0000 doc/developer: add a source tree layout section The section makes a file's path name what the file is and the logical group it belongs to. It sets the rules for subsystem directories, file names, includes, Makefiles and commits that move files. --- doc/developer.texi | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/doc/developer.texi b/doc/developer.texi index 92ccedd381..5ab6dbee81 100644 --- a/doc/developer.texi +++ b/doc/developer.texi @@ -380,6 +380,74 @@ 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. +@anchor{Source tree layout} +@section Source tree layout + +A file's path tells the reader what the file is. +It also tells the reader which logical group the file belongs to. +The rules below follow from this principle. + +@subsection Directories + +A subsystem is the set of files implementing one format, codec or shared +feature, for example Ogg or ID3v2. +A subsystem made of more than one file lives in its own directory inside its +library, for example @file{libavformat/ogg/}. +A nested directory groups related files within a subsystem, for example the +per-codec mappings (@code{struct ogg_codec}) in @file{libavformat/ogg/mapping/}. + +@subsection File names + +Inside a subsystem directory, file names drop the subsystem prefix. +The directory already carries it. + +A file name states the file's role in full words, for example +@file{demuxer.c}, @file{muxer.c}, @file{decoder.c}, @file{encoder.c}, +@file{parser.c}, @file{reader.c} or @file{writer.c}. +Abbreviations would be ambiguous across libraries. +For example, @samp{dec} means a decoder in libavcodec and a demuxer in +libavformat. + +A header shared by a subsystem is named after it. +It sits next to the subsystem's directory, for example @file{libavformat/id3v2.h} +next to @file{libavformat/id3v2/}. +Its include path then reads as the subsystem's name. + +Files that predate these rules keep their names until a commit moves them. + +@subsection Includes + +A file includes headers from its own directory by their bare name, for example +@code{#include "mapping.h"}. +It includes all other headers by their path from the source root, for example +@code{#include "libavformat/ogg/mapping.h"}. +The include path then names the group each header belongs to. + +@subsection Build system + +Each subsystem directory has its own @file{Makefile}. +It lists the objects of the components the subsystem implements, with paths +relative to the library, for example +@code{OBJS-$(CONFIG_OGG_DEMUXER) += ogg/demuxer.o}. +It also has a @code{clean::} rule for each of its directories. +The library @file{Makefile} includes it. +Other components list the subsystem objects they use in their own +@file{Makefile}. + +@subsection Moving files + +A commit that moves files changes nothing else. +It updates only what refers to the moved files: includes, Makefiles, +@file{MAINTAINERS} and @file{.forgejo/CODEOWNERS}. +This lets git's rename detection carry pending patches and backports across +the move. +Patches written against the old paths apply with @command{git am -3}. + +Renaming symbols to match the new layout happens in one commit after the move. +That commit also realigns the lines the rename shifts. + +Each subsystem moves in its own commit. + @section Miscellaneous conventions @itemize @bullet -- To stop receiving notification emails like this one, please contact [email protected]. _______________________________________________ ffmpeg-cvslog mailing list -- [email protected] To unsubscribe send an email to [email protected]
