clang-format: Regroup sort orders

Utilise the clang-format header sort to provide a regex based pattern
match for our header inclusion coding style.

The rules are updated to match as closely as possible the existing
practices and the documentation is updated accordingly.

Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Jean-Michel Hautbois <jeanmichel.hautbois@ideasonboard.com>
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>

.clang-format

@@ -66,10 +66,57 @@ ExperimentalAutoDetectBinPacking: false
 FixNamespaceComments: true
 ForEachMacros:
   - 'udev_list_entry_foreach'
-IncludeBlocks: Preserve
+SortIncludes: true
+IncludeBlocks: Regroup
 IncludeCategories:
-  - Regex: '.*'
+  # Headers matching the name of the component are matched automatically.
-    Priority: 1
+  # Priority 1
+  # Other library headers (explicit overrides to match before system headers)
+  - Regex:           '(<jpeglib.h>|<libudev.h>|<tiffio.h>|<xf86drm.h>|<xf86drmMode.h>|<yaml.h>)'
+    Priority:        9
+  # Qt includes (match before C++ standard library)
+  - Regex:           '<Q([A-Za-z0-9\-_])+>'
+    Priority:        9
+    CaseSensitive:   true
+  # Headers in <> with an extension. (+system libraries)
+  - Regex:           '<([A-Za-z0-9\-_])+\.h>'
+    Priority:        2
+  # System headers 
+  - Regex:           '<sys/.*>'
+    Priority:        2
+  # C++ standard library includes (no extension)
+  - Regex:           '<([A-Za-z0-9\-_/])+>'
+    Priority:        2
+  # Linux headers, as a second group/subset of system headers
+  - Regex:           '<linux/.*>'
+    Priority:        3
+  # Headers for libcamera Base support
+  - Regex:           '<libcamera/base/private.h>'
+    Priority:        4
+  - Regex:           '<libcamera/base/.*\.h>'
+    Priority:        5
+  # Public API Headers for libcamera, which are not in a subdir (i.e. ipa/,internal/)
+  - Regex:           '<libcamera/([A-Za-z0-9\-_])+.h>'
+    Priority:        6
+  # IPA Interfaces
+  - Regex:           '<libcamera/ipa/.*\.h>'
+    Priority:        7
+  # libcamera Internal headers in ""  
+  - Regex:           '"libcamera/internal/.*\.h"'
+    Priority:        8
+  # Other libraries headers with one group per library (.h or .hpp)
+  - Regex:           '<.*/.*\.hp*>'
+    Priority:        9
+  # local modular includes "path/file.h" (.h or .hpp)
+  - Regex:           '"(.*/)+.*\.hp*"'
+    Priority:        10
+  # Other local headers "file.h" with extension (.h or .hpp)
+  - Regex:           '".*.hp*"'
+    Priority:        11
+  # Any unmatched line, separated from the last group
+  - Regex:	     '"*"'
+    Priority:        100
+
 IncludeIsMainRegex: '(_test)?$'
 IndentCaseLabels: false
 IndentPPDirectives: None

Documentation/coding-style.rst

@@ -70,19 +70,30 @@ macro. For .cpp files, if the file implements an API declared in a header file,
 that header file shall be included first in order to ensure it is
 self-contained.
 
+While the following list is extensive, it documents the expected behaviour
+defined by the clang-format configuration and tooling should assist with
+ordering.
+
 The headers shall be grouped and ordered as follows:
 
 1. The header declaring the API being implemented (if any)
 2. The C and C++ system and standard library headers
-3. Other libraries' headers, with one group per library
+3. Linux kernel headers
-4. Other project's headers
+4. The libcamera base private header if required
+5. The libcamera base library headers
+6. The libcamera public API headers
+7. The libcamera IPA interfaces
+8. The internal libcamera headers
+9. Other libraries' headers, with one group per library
+10. Local headers grouped by subdirectory
+11. Any local headers
 
 Groups of headers shall be separated by a single blank line. Headers within
 each group shall be sorted alphabetically.
 
 System and library headers shall be included with angle brackets. Project
 headers shall be included with angle brackets for the libcamera public API
-headers, and with double quotes for other libcamera headers.
+headers, and with double quotes for internal libcamera headers.
 
 
 C++ Specific Rules