Why does ctx.actions.args.param_file_arg accept a constant argument

[ittaiz]

ATTENTION! Please read and follow:

• if this is a question about how to build / test / query / deploy using Bazel, or a discussion starter, send it to [email protected]
• if this is a bug or feature request, fill the form below as best as you can.

Description of the problem / feature request:

I'm now using ctx.actions.args.param_file_arg and U don't understand why we need to pass a constant argument ("%s"). If it's constant why not hide it from the user?

What's the output of bazel info release?

2.0.0

Have you found anything relevant by searching the web?

https://docs.bazel.build/versions/master/skylark/lib/Args.html#use_param_file

[laurentlb]

The argument needs to contain %s, but it can be for example "@%s" or "--param_file=%s".

[ittaiz]

What do these options mean? Are they documented? I’m not trying to troll but I honestly don’t understand the API choice here

[ulfjack]

The question is: what does the tool you're calling expect?

If it's just the filename, then pass "%s". For gcc and clang, the tool expects "@%s". The '%s' substring is replaced with the filename, so for gcc, the invocation is actually "gcc @param-file". Does that make sense?

In some cases Bazel decides whether to use a param file on-the-fly depending on the actual size of the command line. I'm not sure if this API exposes that or if it can be controlled. Note that there is a Bazel build command-line flag to force it to always use param files.

[laurentlb]

No worries, it just shows that the documentation needs improvement and examples.

If you take gcc, you can call it like this:

$ gcc hello.c -c

To use a params file, you will do instead:

$ echo "hello.c -c" > params.txt
$ gcc @params.txt

That's gcc command-line syntax. To pass a param file, you need to put @ and then the file.
Other tools might use different a convention, e.g. --file=params.txt.

So when you want to use a param file, you tell Bazel how to pass the argument to the tool, such as "@%s" or "--file=%s". Bazel will replace %s with the path to the file.

[ittaiz]

Thank you both for explaining!
Do you think there’s room for a default value here or is the landscape really diverse and so a default doesn’t make sense?

[laurentlb]

It seems that @file is common among Linux tools (https://stackoverflow.com/a/13040192). Inside Google, most calls to param_file_arg use another value (but not always the same).

I think it's better not to have a default value. The user should really check with the tool is expecting. I'll keep this issue open as a documentation problem.

[ittaiz]

SGTM. Thanks for the clarifications.