search

immunant / IA2-Phase2

4 stars 0 forks source link

Rewriter command-line interface is inscrutable #328

Open fw-immunant opened 3 months ago

fw-immunant commented 3 months ago

Some of this we can't easily solve because it comes from libClangTooling's built-in behavior, but I wanted to at least dump my notes as partial documentation:

The --help usage message suggests:

USAGE: ia2-rewriter [options] <source0> [... <sourceN>]

but it also accepts, after sources, a -- followed by arbitrary compiler flags, where if -- is present, the built-in flags (e.g. where the compiler would learn where to find stddef.h) seem to be ignored and -I /usr/lib/clang/${CLANG_MAJOR}/include must be passed to find built-in headers. We do this in our ffmpeg/libusb tests with -I %resource_dir.

In some of my tests running the rewriter in this way clears the content of all files in runtime/libia2/include, which is highly unexpected.

This mode also overlaps with the possible use cases for --extra-arg, and it isn't clear to a user which to prefer or how they interact.

In addition, the -p flag is documented as -p <string> - Build path: this does not make it all clear that this is a path to a directory within in which compile_commands.json will be looked for.

ayrtonm commented 3 months ago

yeah I feel like we can't easily fix any of these help messages w/o modifying libClang so I'd say we should just update the docs on how to run the rewriter and add notes on these issues.