sync with OpenBSD -current

lib/mesa/docs/codingstyle.rst

@@ -8,7 +8,103 @@ of mesa can use different coding style as set in the local EditorConfig
 following is applicable. If the guidelines below don't cover something,
 try following the format of existing, neighboring code.
 
+``clang-format``
+----------------
+
+A growing number of drivers and components are adopting ``clang-format``
+to standardize the formatting and make it easy for everyone to apply it.
+
+You can re-format the code for the components that have opted-in to the
+formatting enforcement (listed in ``.clang-format-include``) by simply
+running ``ninja -C build/ clang-format``.
+
+Since mass-reformatting commits can be an annoying extra jump to go
+through when looking at ``git blame``, you can configure it to ignore
+them by running::
+
+  git config blame.ignoreRevsFile .git-blame-ignore-revs
+
+Most code editors also support automatically formatting code as you
+write it; check your editor or its pluggins to see how to enable this.
+
+Vim
+***
+
+Add this to your ``.vimrc`` to automatically format any C & C++ file
+(that has a .clang-format config) when you save it:
+
+.. code:: vim
+
+   augroup ClangFormatOnSave
+     au!
+
+     function! ClangFormatOnSave()
+       " Only format files that have a .clang-format in a parent folder
+       if !empty(findfile('.clang-format', '.;'))
+         let l:formatdiff = 1 " Only format lines that have changed
+         py3f /usr/share/clang/clang-format.py
+       endif
+     endfunction
+
+     autocmd BufWritePre *.h,*.c,*.cc,*.cpp call ClangFormatOnSave()
+   augroup END
+
+If ``/usr/share/clang/clang-format.py`` doesn't exist, try
+``/usr/share/clang/clang-format-$CLANG_VERSION/clang-format.py``
+(replacing ``$CLANG_VERSION`` with your clang version). If your distro
+has put the file somewhere else, look through the files in the package
+providing ``clang-format``.
+
+Emacs
+*****
+
+Add this to your ``.emacs`` to automatically format any C & C++ file
+(that has a .clang-format config) when you save it:
+
+.. code:: emacs
+
+   (load "/usr/share/clang/clang-format.el")
+
+   (defun clang-format-save-hook-for-this-buffer ()
+     "Create a buffer local save hook."
+     (add-hook 'before-save-hook
+               (lambda ()
+                 (when (locate-dominating-file "." ".clang-format")
+                   (clang-format-buffer))
+                 ;; Continue to save.
+                 nil)
+               nil
+               ;; Buffer local hook.
+               t))
+
+   ;; Run this for each mode you want to use the hook.
+   (add-hook 'c-mode-hook (lambda () (clang-format-save-hook-for-this-buffer)))
+   (add-hook 'c++-mode-hook (lambda () (clang-format-save-hook-for-this-buffer)))
+
+If ``/usr/share/clang/clang-format.el`` doesn't exist, look through the
+files in the package providing ``clang-format`` in your distro. If you
+can't find anything (eg. on Debian/Ubuntu), refer to `this StackOverflow
+answer <https://stackoverflow.com/questions/59690583/how-do-you-use-clang-format-on-emacs-ubuntu/59850773#59850773>`__
+to install clang-format through Emacs instead.
+
+git ``pre-commit`` hook
+***********************
+
+If your editor doesn't support this, or if you don't want to enable it, you
+can always just run ``ninja clang-format`` to format everything, or add
+a ``pre-commit`` hook that runs this automatically whenever you ``git
+commit`` by adding the following in your ``.git/hooks/pre-commit``:
+
+.. code:: sh
+
+   shopt -s globstar
+   git clang-format $upstream -- $(grep -E '^[^#]' .clang-format-include)
+   # replace $upstream with the name of the remote tracking upstream mesa
+   # if you don't know, it's probably `origin`
+
+
 Basic formatting guidelines
+---------------------------
 
 -  3-space indentation, no tabs.
 -  Limit lines to 78 or fewer characters. The idea is to prevent line