Issue 975 in include-what-you-use: Confusion about path/to/iwyu; Clang 11 and Clang 13 failed to use

[notifi...@include-what-you-use.org]

New issue 975 by zchrissirhcz: Confusion about path/to/iwyu; Clang 11 and Clang 13 failed to use
https://github.com/include-what-you-use/include-what-you-use/issues/975

Hi, iwyu developers

I use CMake for my C++ project, would like to integrate iwyu it with cmake. I found the usage in this project's readme page:

```bash
mkdir build && cd build
CC="clang" CXX="clang++" cmake -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE="path/to/iwyu;-Xiwyu;any;-Xiwyu;iwyu;-Xiwyu;args" ...
```

I'm in confusion with those.

- I don't know what exactly `path/to/iwyu` mean, is that the absolute path of the executable `iwyu` ?
- I build include-what-you-use from source, the executable I get is `include-what-you-use` instead of `iwyu`
- I don't know what exactly does `-Xiwyu;any;-Xiwyu;iwyu;-Xiwyu;args` mean, should I change them, or keep them anyway?
- I'm using Clang 13, and the build-from-latest-source include-what-you-use just failed for very simple code
```c++
#include <stdio.h> // this line is expected to be reported
int main()
{
return 0;
}
```
- I switch to clang11.0, with include-what-you-use clang_11 branch, but it also failed to report

[notifi...@include-what-you-use.org]

Comment #1 on issue 975 by kimgr: Confusion about path/to/iwyu; Clang 11 and Clang 13 failed to use
https://github.com/include-what-you-use/include-what-you-use/issues/975

`/path/to/iwyu` and `-Xiwyu;any;-Xiwyu;args` are both brief placeholders, I think they assume you know what the `include-what-you-use` command line looks like.

> I don't know what exactly path/to/iwyu mean, is that the absolute path of the executable iwyu ?

> I build include-what-you-use from source, the executable I get is include-what-you-use instead of iwyu

Yes, make it the absolute path to the `include-what-you-use` executable.

> I don't know what exactly does -Xiwyu;any;-Xiwyu;iwyu;-Xiwyu;args mean, should I change them, or keep them anyway?

IWYU's command-line is a little strange. It accepts all compiler arguments just like the `clang` compiler, so for example `-I/usr/include/somelib` and `-DFOO=BAR` are accepted and passed directly onto the Clang front-end for parsing.

Any IWYU arguments need to be prefixed with `-Xiwyu`, e.g. `-Xiwyu --verbose=4` or `-Xiwyu --no_comments`.

What the example is trying to say is that you need to put any additional arguments as a semicolon-separated list, and if they are IWYU-specific arguments, they need to be `-Xiwyu`-prefixed.

So if your direct `include-what-you-use` command was `/code/build/bin/include-what-you-use -Xiwyu --verbose=7 -Xiwyu --cxx17ns ...build args... mysourcefile.cc`, the CMake command would be:
```
cmake -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE="/code/build/bin/include-what-you-use;-Xiwyu;--verbose=7;-Xiwyu;--cxx17ns"`
```

(note that `...build args...` in the first example is a place holder for any compiler flags normally provided by the build system. They are provided by CMake automatically, so you only need to add any custom IWYU args)

[notifi...@include-what-you-use.org]

Comment #1 on issue 975 by zchrissirhcz: Confusion about path/to/iwyu; Clang 11 and Clang 13 failed to use
https://github.com/include-what-you-use/include-what-you-use/issues/975

Well I think it would be more clear for me, if the tutorial just write as this:

To use include-what-you-use with cmake integration, just insert one line:
```cmake
set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE "include-what-you-use")
```
This assumes `include-what-you-use` in your PATH, and if not, consider change it to absolute path. Also, `CMAKE_CXX_INCLUDE_WHAT_YOU_USE` support adding options, such as:
```cmake
set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE "/path/to/include-what-you-use;-Xiwyu;--verbose=7;-Xiwyu;--cxx17ns")
```

People may also change this globally setting to per-target setting, i.e.
```cmake
set(iwyu_path_and_options
"/path/to/include-what-you-use" # path
"some include-what-you-use options"
)

set_property(TARGET testbed
PROPERTY CXX_INCLUDE_WHAT_YOU_USE ${iwyu_path_and_options})
```