This is an automated email from Gerrit. "Yasushi SHOJI <[email protected]>" just uploaded a new patch set to Gerrit, which you can find at https://review.openocd.org/c/openocd/+/6542
-- gerrit commit 94b077307cabe3c944adf961d10d2334b6e2224a Author: Yasushi SHOJI <[email protected]> Date: Sun Sep 5 23:12:05 2021 +0900 doc/manual: Add style guide for C include files Add our style guide for C include files. Change-Id: I3eb88409bb73ee7bae0c5c0be660ccd7a755e157 Signed-off-by: Yasushi SHOJI <[email protected]> diff --git a/doc/manual/style.txt b/doc/manual/style.txt index 58f39807e..f45965608 100644 --- a/doc/manual/style.txt +++ b/doc/manual/style.txt @@ -138,6 +138,44 @@ this: #endif /* OPENOCD_HELPER_JIM_NVP_H */ @endcode +@section styleincludes Include Files + +OpenOCD source files are organized in a way that each folder builds +into a library. Each folder is given the following include paths for +both source and build directories. + +- src/ +- A path to @c jim.h (either system include path or @c jimctl/) +- A path to @c libjaylink/ (in case of jtag drivers) + +Thus, when you want to reference any header file in the code base, you +must use path under `src/`. + +@code +#include "helper/align.h" +@endcode + +Include files in a C source file should be in the following order: + +-# Self header file +-# A blank line +-# C system headers in angle brackets +-# A blank line +-# Library header files in angle brackets +-# A blank line +-# Local header files in double quotes + +If a source file has something to export, put them in a header file in +the same directory, and include the header file by itself. In this +way, you can verify the signatures against the source file. + +Because both `jimtcl` and `libjaylink` are external entities included +using `git submodule`, both libraries should be treated as "Library +header files in angle brackets" and header files should be placed in +angle brackets. + +Lines in each section must be alphabetically sorted. + @section stylec99 C99 Rules - inline functions --
