incompatible_display_source_file_location: incompatible flag for query output location

[zhengwei143]

Flag: --incompatible_display_source_file_location
Available since: Yet to be released
Will be flipped in: To be confirmed

Motivation

Brought to light by github issue.

Current documentation defines the --output=location flag to print the location of line 1 of source files. However, current implementations only print the target of the source file. For example:

[Expected] Current definition:

$ bazel query bazeltest:main.py --output=location
/home/tanzhengwei/bazeltest/main.py:1:1: source file //bazeltest:main.py

[Actual] Current implementation:

$ bazel query bazeltest:main.py --output=location
/home/tanzhengwei/bazeltest/BUILD:1:10: source file //bazeltest:main.py

Changes

Appending the flag --incompatible_display_source_file_location will change the current implementation to fit the expected definition.

After the flip, modifies the current implementation to match the current definition. The default will use the --incompatible_display_source_file_location flag and print out the location of line 1 of source files instead of their targets.

EDIT: Similarly, when using --output=proto and --output=xml together with --incompatible_display_source_file_location, the location of source files will printed similar to --output=location.

Migration

After the flip, scripts that use the output of bazel query --output=location and more specifically the source file location /home/tanzhengwei/bazeltest/BUILD:1:10 will be affected by this change. To fix your scripts, you would likely need to use some sed transformation to modify the output accordingly.

However, it might be a problem if your script requires the use of the location (specifically the row and column) of the source file in the BUILD file, since this is being phased out and will not contain any information about it.

[benjaminp]

Is it intentional that the source files names are all suffixed with :1:1?

[zhengwei143]

Yes, by definition, other than the path, the location also includes the row and column in the file. This is aligned with the definition as currently stated in the docs "For source files, the location of line 1 of the actual file is printed".

[benjaminp]

That documentation doesn't justify the new behavior. The first paragraph of the --output location documentation states that the first field of each line is a location. The second paragraph describes what that location is for each kind of target. In fact, source files are not prefixed by the "the location of line 1 of the actual file" in the current implementation; the prefix is a location in the containing package's BUILD file.

It would make sense to keep the :1:1 location if the prefix was actually the path to the source file to preserve the consistency of the "grep format".

If changing the location prefix to cohere with the documentation isn't in the works, the new output should be evaluated for its utility. Semantically, a source file target refers to the whole file not in particular its first line and column. On a practical level, the :1:1 must be stripped by any tool making use of --output location specifically for source files because it is meaningless.

[zhengwei143]

You're right, I've misunderstood the documentation previously. Thanks for pointing it out.

I've added you as a reviewer to the PR that fixes this and modified the description above.

[alandonovan]

This feature cannot be implemented as described, because the actual location of a generated file target is not known during package loading; it is a function of the configuration, computed during analysis. In other words, the best blaze query can do is a white lie:

$ cat p/BUILD
genrule(name='g', outs=['o'], cmd=':')

$ blaze query --output=location //p:o | sed -e s?$(pwd)/??
p/o:1:8: generated file //p:o  # actual result today is p/BUILD. Correct result is blaze-bin/.../p/o

EDIT: Never mind, this feature is restricted to source files. Carry on.

[noscript]

It seems the new behavior is already present in Bazel 5.1.1 but that change broke my tools. Is there a way to get the old behavior back? I can no longer query the build file, along with the line and column number.

UPDATE: --noincompatible_display_source_file_location reverts the old behavior.