Fix compile args, add fix and system_last options

.github/workflows/ubuntu_latest.yml

@@ -16,7 +16,7 @@ jobs:
     steps:
     - uses: actions/checkout@v6
 
-    - run: sudo apt-get install iwyu
+    - run: sudo apt-get update && sudo apt-get install -y iwyu
 
     - run: |
         $CURL_GET -o mkn ${PATH_GET}/mkn_nix

README.md

@@ -1,34 +1,65 @@
 # cpp.iwyu
 
-** Compile stage plugin to to run include-what-you-use on all applicable files **
+**Compile phase module running [include-what-you-use](https://include-what-you-use.org) on project sources**
+
+Each file is checked with the same flags its real compilation uses. iwyu's suggestions are printed,
+they do not fail the build.
 
 ## Prerequisites
-  [maiken](https://github.com/mkn/mkn)
+
+- [maiken](https://github.com/mkn/mkn)
+- `iwyu` or `include-what-you-use` on `PATH`
 
 ## Usage
 
 ```yaml
 mod:
 - name: cpp.iwyu
   compile:
-    headers: -x c++-header      # h files need this for scanning if they are C++
-    args: -std=c++17            # additional arguments
-    inc: inc/1 inc/2            # additional include directories
-    paths: search/dir           # scan directories
-    ignore: src/python3         # if file found has path that contains string ignore
-    types: cpp hpp cc           # file types checked default:  {"cpp", "cxx", "cc", "cc", "h", "hpp"}
-
+    args: -DSOME_DEFINE        # additional arguments
+    headers: -x c++-header     # additional arguments for header files (h hh hpp hxx)
+    inc: inc/1 inc/2           # additional include directories
+    paths: search/dir          # also check files found in these directories
+    ignore: src/python3 tpp    # skip files whose path contains any of these
+    types: cpp hpp cc          # file types checked, default: cpp cxx cc h hpp
+    fix: --nocomments          # apply the suggestions with fix_include, using these arguments
+    system_last: true          # with fix, put system includes after project includes
 ```
 
-## Building
+Every key is optional, the project's own source files are always checked. Lists are space
+separated, `types` may also be `:` separated.
+
+## Applying suggestions
+
+With `fix`, iwyu's output is written to `<build dir>/iwyu.out` and passed to iwyu's `fix_include`
+(`fix_includes.py` upstream), which edits the files. `fix: ""` uses `fix_include`'s defaults. Useful arguments:
 
-  *nix gcc:
+| argument | effect |
+|---|---|
+| `-n` | print the diffs, do not edit |
+| `--nocomments` | no `// for X` comments after includes |
+| `--nosafe_headers` | also remove includes from headers, by default headers only get additions |
+| `--noreorder` | do not reorder existing includes, for order sensitive includes |
+| `--ignore_re REGEX` | do not edit matching files |
 
-    mkn clean build -dtOa "-fPIC" -l "-pthread -ldl"
+`fix_include` puts system includes first. With `system_last: true` the module then moves them after
+the project includes in every file it edited, so a system include cannot hide a project header
+missing its own includes. Only contiguous runs of `#include` lines are reordered, blank line separated groups keep
+their order, includes in `#if` sections stay where they are.
 
+Edits happen during the compile phase, so the edited files are what get compiled. Running `fix`
+from its own profile keeps it out of normal builds.
+
+## Building
+
+```bash
+mkn clean build -dtOa "-std=c++20 -fPIC"
+```
 
 ## Testing
 
-  *nix gcc:
+Runs iwyu over this module's own source:
 
-    mkn clean build -dtOa "-fPIC" -l "-pthread -ldl" -p test run
+```bash
+mkn clean build -dtOa "-std=c++20 -fPIC" -p iwyu
+```

mkn.yaml

@@ -1,26 +1,27 @@
+#! clean build -dtOa "-std=c++20 -fPIC" -p iwyu
 
 name: cpp.iwyu
 version: master
-property:
-    maiken_location: ${MKN_HOME}/app/mkn/${version}
-    maiken_scm: https://github.com/mkn/mkn
 
 parent: base
 src: mod.cpp
 mode: shared
 
 profile:
 - name: base
-  dep: mkn.mod mkn#${version}&${maiken_location}(${maiken_scm})[headers]
+  dep: mkn.mod
   if_arg:
       win_shared: -DYAML_CPP_DLL
       shared: -DMKN_KUL_SHARED
 
 - name: format
   mod: |
-    clang.format{init{style: google, paths: .}}
+    clang.format{init{style: file, paths: .}}
 
+# runs iwyu over this module's own source and applies its suggestions
 - name: iwyu
   parent: base
+  src: mod.cpp
+  # inline form, the list form resolves the module from the default branch in CI
   mod: |
-    cpp.iwyu{init{args: -std=c++17, paths: .}}
+    cpp.iwyu{compile{fix: --nocomments --nosafe_headers, system_last: true}}