Understanding Options.td

I am looking at adding an option that should only be passed by the user
at link time. The option affects how clang behaves and does not get
passed to the linker itself. Clang should warn if the option is given
in a non-linking context.

Looking at Driver/Options.td, I see a couple of definitions that might
be relevant:

// LinkerInput - The option is a linker input.
def LinkerInput : OptionFlag;

def Link_Group : OptionGroup<"<T/e/s/t/u group>">, DocName<"Linker flags">,
                 DocBrief<[{Flags that are passed on to the linker}]>;

I also see some uses of these:

def hip_device_lib_path_EQ : Joined<["--"], "hip-device-lib-path=">, Group<Link_Group>,
  HelpText<"HIP device library path">;
def hip_device_lib_EQ : Joined<["--"], "hip-device-lib=">, Group<Link_Group>,
  HelpText<"HIP device library">;

def framework : Separate<["-"], "framework">, Flags<[LinkerInput]>;

I am not sure how to interpret this. On the one hand, I imagine the HIP
options are options that affect how clang behaves but do not get passed
to the linker, so Link_Group seems like the right things to use. On the
other hand, I don't think linkers support a -framework option so maybe
LinkerInput is what I should use. I don't know what "linker input"
means, nor what "passed on to the linker" means given what I am seeing
in Options.td.

Is there some guidance on the use of Flags and Group for options? What
is the right incantation for my needs?

Thanks!

                            -David

I haven’t looked - but my first guess at an argument to seek inspiration from, would be -fuse-ld. See how that’s handled, how it warns if the compiler isn’t doing a link action, etc.

David Blaikie via cfe-dev <cfe-dev@lists.llvm.org> writes:

I haven't looked - but my first guess at an argument to seek
inspiration from, would be -fuse-ld. See how that's handled, how it
warns if the compiler isn't doing a link action, etc.

I grepped around but didn't see anything obvious that tells clang to
emit the warning for use in a non-linking context. clang does emit the
warning so I am puzzled about how that happens.

The definition looks simple enough:

def fuse_ld_EQ : Joined<["-"], "fuse-ld=">, Group<f_Group>, Flags<[CoreOption]>;

It must not have anything to do with the TableGen definition.

                           -David

Nah, the warnings are emitted whenever the option isn’t queried dynamically by the frontend, I believe. So it’s implicit in the options usage - code doesn’t use it? Warnings get emitted.

Usually if I’m curious about this sort of thing I set breakpoints in the diagnostnic printing infrastructure and run the program to see what motivated it to trigger.

David Blaikie via cfe-dev <cfe-dev@lists.llvm.org> writes:
> I haven't looked - but my first guess at an argument to seek
> inspiration from, would be -fuse-ld. See how that's handled, how it
> warns if the compiler isn't doing a link action, etc.

I grepped around but didn't see anything obvious that tells clang to
emit the warning for use in a non-linking context. clang does emit the
warning so I am puzzled about how that happens.

Clang warns on all command-line arguments that are not "claimed".
Arguments are "claimed" by any operation that looks for them (eg,
getLastArg, hasFlag, ...) as well as by explicit ClaimAllArgs calls.
So, if you add a new option, then by default you get the "unused
option" diagnostic for free, and the diagnostic is automatically
suppressed if you actually use the argument in the driver (eg, by
looking for it, or by passing it into some subtool invocation).

Groups in Options.td serve a few purposes:

- they (optionally) control how the --help output is grouped (if
HelpText is provided)
- they (optionally) control how
http://clang.llvm.org/docs/ClangCommandLineReference.html is grouped
(if DocFlatten is not specified)
- they control how the arguments are grouped by tools that dump
clang's list of arguments (I think XCode does this and tab-completion
might do so too)
- they provide a mechanism to allow the driver code to easily refer
to all arguments of a given kind, for instance to propagate all flags
of some kind to a subtool or claim all of them (grep for _Group in
lib/Driver to see these cases)

If you're referring to the usual "unused option" warning, that gets
emitted for any option that is not "claimed" meaning that some code
looked to see whether it is present. For things like -fuse-ld, the
driver only looks for it if it sees that it needs to build a linker
job. If you troll around the Driver library for OPT_fuse_ld I think
you'll find that only linker-related paths look for it. There's
nothing special attached to the option that says "linker-only context."
--paulr