[dev] Style guidelines

[Quentin Young]

Greetings developers, here is a reminder of the style guide and a summary of the tools FRR offers you to minimize the effort you spend ensuring your patches are compliant.

FRR uses Linux kernel style. You can find that documented here: https://www.kernel.org/doc/html/v4.10/process/coding-style.html <https://www.kernel.org/doc/html/v4.10/process/coding-style.html>

FRR’s style requirement is that patches submitted to FRR must comply with this style (with some exceptions covered in the docs). You are not required to run any tool, any script, etc, before submitting your patch. Feel free to do everything by hand if you want. If it complies with the style guidelines then from a style standpoint it is fine.

FRR offers you a variety of tools for your convenience to help comply with the style guidelines and make it as easy as possible. In no particular order these are:

* clang-format configuration file

In the project root there is a file named .clang-format. This is a configuration file for the clang-format source formatting tool. This tool is part of the LLVM project. If you wish, you can use this tool to assist in complying with the style guide. There are good integrations for most editors, as well as an integration with git that you can use to do things like only format lines introduced in certain commits, only format staged changes, etc. Please note that while clang-format gets you 95% of the way there it’s not perfect and you are still responsible for styling your code properly.

* indent.py

This is a script that takes a filename and formats it with clang-format, doing some additional preprocessing to help reduce some edge-case mangling that happens with things like DEFUNs and macros. It operates on whole files. Usually you’re better off using clang-format integrations to format your code as you go.

* tools/checkpatch.sh

This is a script that wraps an adapted version of the Linux kernel’s checkpatch.pl script. It takes a git formatted patch or diff file and a path to your frr tree and does some magic to warn you about potential style issues. It does modify your frr tree in the process although it makes a best effort to save your working tree and restore it, if you don’t want to use `git stash` for some reason. You can run it like this:

cd tools/
./checkpatch.sh /path/to/patchfile /path/to/frr/sourcetree

This script is also run by the CI system on new pull requests and its output is displayed to assist you with catching style errors. It’s not perfect but should catch the majority and have a relatively low false positive rate. DEFUNs are ignored so please use common sense when formatting these to avoid spending others’ time reviewing style.

As always if you have any questions about style please refer to the kernel style guide, if you can’t find the answer to your question there ask on slack or this mailing list, and if you have improvements to indent.py or checkpatch.sh ideally submit a patch or alternatively open a Github issue. Again you are not required to use these tools, they are here for your personal convenience. We do not maintain clang-format so please don’t open bugs or feature requests about clang-format with us.

Quentin
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.frrouting.org/pipermail/dev/attachments/20180222/e3906fc3/attachment.html>