Edit
IABSD.fr/xenocara/lib/mesa/docs/codingstyle.rst
jsg
- lib/mesa/docs/codingstyle.rst
-
Coding Style ============ Mesa is over 20 years old and the coding style has evolved over time. Some old parts use a style that's a bit out of date. Different sections of mesa can use different coding style as set in the local EditorConfig (.editorconfig) and/or Emacs (.dir-locals.el) file. Alternatively the 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 plug-ins 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 (e.g. 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 wrapping in 80-column editors and terminals. There are exceptions, such as if you're defining a large, static table of information. - Opening braces go on the same line as the if/for/while statement. For example: .. code-block:: c if (condition) { foo; } else { bar; } - Put a space before/after operators. For example, ``a = b + c;`` and not ``a=b+c;`` - This GNU indent command generally does the right thing for formatting: .. code-block:: sh indent -br -i3 -npcs --no-tabs infile.c -o outfile.c - Use comments wherever you think it would be helpful for other developers. Several specific cases and style examples follow. Note that we roughly follow `Doxygen <https://www.doxygen.nl>`__ conventions. Single-line comments: .. code-block:: c /* null-out pointer to prevent dangling reference below */ bufferObj = NULL; Or, .. code-block:: c bufferObj = NULL; /* prevent dangling reference below */ Multi-line comment: .. code-block:: c /* If this is a new buffer object id, or one which was generated but * never used before, allocate a buffer object now. */ We try to quote the OpenGL specification where prudent: .. code-block:: c /* Page 38 of the PDF of the OpenGL ES 3.0 spec says: * * "An INVALID_OPERATION error is generated for any of the following * conditions: * * * <length> is zero." * * Additionally, page 94 of the PDF of the OpenGL 4.5 core spec * (30.10.2014) also says this, so it's no longer allowed for desktop GL, * either. */ Function comment example: .. code-block:: c /** * Create and initialize a new buffer object. Called via the * ctx->Driver.CreateObject() driver callback function. * \param name integer name of the object * \param type one of GL_FOO, GL_BAR, etc. * \return pointer to new object or NULL if error */ struct gl_object * _mesa_create_object(GLuint name, GLenum type) { /* function body */ } - Put the function return type and qualifiers on one line and the function name and parameters on the next, as seen above. This makes it easy to use ``grep ^function_name dir/*`` to find function definitions. Also, the opening brace goes on the next line by itself (see above.) - Function names follow various conventions depending on the type of function: +---------------------+------------------------------------------+ | Convention | Explanation | +=====================+==========================================+ | ``glFooBar()`` | a public GL entry point (in | | | :file:`glapi_dispatch.c`) | +---------------------+------------------------------------------+ | ``_mesa_FooBar()`` | the internal immediate mode function | +---------------------+------------------------------------------+ | ``save_FooBar()`` | retained mode (display list) function in | | | :file:`dlist.c` | +---------------------+------------------------------------------+ | ``foo_bar()`` | a static (private) function | +---------------------+------------------------------------------+ | ``_mesa_foo_bar()`` | an internal non-static Mesa function | +---------------------+------------------------------------------+ - Constants, macros and enum names are ``ALL_UPPERCASE``, with \_ between words. - Mesa usually uses camel case for local variables (Ex: ``localVarname``) while Gallium typically uses underscores (Ex: ``local_var_name``). - Global variables are almost never used because Mesa should be thread-safe. - Booleans. Places that are not directly visible to the GL API should prefer the use of ``bool``, ``true``, and ``false`` over ``GLboolean``, ``GL_TRUE``, and ``GL_FALSE``. In C code, this may mean that ``#include <stdbool.h>`` needs to be added. The ``try_emit_*`` method ``src/mesa/state_tracker/st_glsl_to_tgsi.cpp`` can serve as an example.