docs: update contributing + FAQ docs for gst-indent

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/5192>
This commit is contained in:
Tim-Philipp Müller 2023-09-29 17:47:53 +02:00 committed by L. E. Segovia
parent fab3da528e
commit 41c097ed6c
2 changed files with 29 additions and 48 deletions

View file

@ -426,25 +426,21 @@ In the simplest case, you might be able to get away with just doing a `git pull
#### Coding Style #### Coding Style
Try to stick to the GStreamer indentation and coding style. There is a script Try to stick to the GStreamer indentation and coding style. There is an
called [`gst-indent`][gst-indent] which you can run over your `.c` or `.cpp` application called [`gst-indent`][gst-indent] which should be available
files if you want your code auto-indented before making the patch. The script in a GStreamer development environment and which you can run over your `.c` or
requires GNU indent to be installed already. Please do _not_ run `gst-indent` on `.cpp` files if you want your code auto-indented before making the patch.
header files, our header file indentation is free-form. If you build GStreamer
from git, a local commit hook will be installed that checks if your commit
conforms to the required style (also using GNU indent).
Different versions of GNU indent may occasionally yield slightly different Please do _not_ run `gst-indent` on header files, our header file
indentations. If that happens, please ignore any indentation changes in indentation is free-form.
sections of code that your patch does not touch. You can do that by staging
changes selectively via `git add -p`. You can bypass the local indentation If you build GStreamer from git, a local commit hook will be installed that
check hook by using `git commit -n`, but it will still be checked again later checks if your commit conforms to the required style. You can bypass that local
when you submit your changes through GitLab for merging. indentation check hook by using `git commit -n`, but it will still be checked
again later on the CI when you submit your changes through GitLab for merging.
We are working on making this less hasslesome. We are working on making this less hasslesome.
[gst-indent]: https://gitlab.freedesktop.org/gstreamer/gstreamer/-/blob/main/scripts/gst-indent-all
Compiler requirements: Compiler requirements:
- we are targetting the C99 compiler and preprocesser feature subset - we are targetting the C99 compiler and preprocesser feature subset
supported by gcc 5.4, clang and vs2017. Newer features can be supported by gcc 5.4, clang and vs2017. Newer features can be
@ -461,7 +457,7 @@ Other style guidelines:
- declare variables inline (as opposed to only at the beginning of a block) - declare variables inline (as opposed to only at the beginning of a block)
- use advanced/nicer struct initialisers - use advanced/nicer struct initialisers
[gst-indent]: https://gitlab.freedesktop.org/gstreamer/gstreamer/tree/master/tools/gst-indent [gst-indent]: https://gitlab.freedesktop.org/gstreamer/gst-indent/
[bitreader]: https://gstreamer.freedesktop.org/documentation/base/gstbitreader.html?gi-language=c#GstBitReader [bitreader]: https://gstreamer.freedesktop.org/documentation/base/gstbitreader.html?gi-language=c#GstBitReader
[bytereader]: https://gstreamer.freedesktop.org/documentation/base/gstbytereader.html?gi-language=c#GstByteReader [bytereader]: https://gstreamer.freedesktop.org/documentation/base/gstbytereader.html?gi-language=c#GstByteReader

View file

@ -106,46 +106,31 @@ want it to do.
## What is the coding style for GStreamer code? ## What is the coding style for GStreamer code?
Basically, the core and almost all plugin modules use K\&R with 2-space The indentation style for GStreamer C code is similar to K\&R with 2-space
indenting. Just follow what's already there and you'll be fine. We only require indenting.
code files to be indented, header may be indented manually for better
readability. Please use spaces for indenting, not tabs, even in header files.
Individual plugins in gst-plugins-\* or plugins that you want considered Consistent indentaiton is enforced only for C source files, we generally do
for addition to these modules should use the same style. It's easier if not indent header files.
everything is consistent. Consistency is, of course, the goal.
In header files indentation is free-form, but please always use spaces and
not tabs since editor settings with regard to tabs will vary. Please do not
run the indenter on existing header files when making changes.
Rust source files (.rs files) are indented with the standard `rustfmt`.
One way to make sure you are following our coding style is to run your code One way to make sure you are following our coding style is to run your code
(remember, only the `*.c` files, not the headers) through GNU Indent using the (remember, only the `*.c` files, not the headers) through the `gst-indent-1.0`
following options: tool, which should be available in the uninstalled GStreamer development
environment from version 1.23.1 onwards. Alternatively you can also get the
``` tool from the [gst-indent repository](https://gitlab.freedesktop.org/gstreamer/gst-indent/)
indent \ and build it yourself.
--braces-on-if-line \
--case-brace-indentation0 \
--case-indentation2 \
--braces-after-struct-decl-line \
--line-length80 \
--no-tabs \
--cuddle-else \
--dont-line-up-parentheses \
--continuation-indentation4 \
--honour-newlines \
--tab-size8 \
--indent-level2
```
There is also a `gst-indent` script in the GStreamer core source tree in the
tools directory which wraps GNU Indent and uses the right options.
The easiest way to get the indenting right is probably to develop against a git The easiest way to get the indenting right is probably to develop against a git
checkout. The local git commit hook will ensure correct indentation. checkout. The local git commit hook will ensure correct indentation.
Comments should be in `/* ANSI C comment style */` and code should generally Merge requests should always be made against git `main` branch and filed
be compatible with ANSI C89, so please declare all variables at the beginning in GitLab.
of the block, etc.
Merge requests should ideally be made against git master or a recent release.
Please don't send patches to the mailing list. They will likely get lost there. Please don't send patches to the mailing list. They will likely get lost there.
See [How to submit patches][submit-patches] for more details. See [How to submit patches][submit-patches] for more details.