Getting runtime path to a package in Bazel toolchain configuration files

Question

What is the best way to refer to an external package's path in any arbitrary files processed by Bazel?

I'm trying to understand how Bazel preprocesses BUILD and .bzl files. I see instances where strings contain calls to package() and I am wondering how it works (and could not find any relevant documentation). Here is an example of this:

I have a toolchain which BUILD file contains the following expression :

cc_toolchain_config(
    name = "cc-toolchain-config",
    abi_libc_version = "glibc_" + host_gcc8_bundle()["pkg_version"]["glibc"],
    abi_version = "gcc-" + host_gcc8_bundle()["version"],
    compiler = "gcc-" + host_gcc8_bundle()["version"],
    cpu = "x86_64",
    cxx_builtin_include_directories = [
        "%package(@host_gcc8_toolchain//include/c++/8)%",
        "%package(@host_gcc8_toolchain//lib64/gcc/x86_64-unknown-linux-gnu/8/include-fixed)%",
        "%package(@host_gcc8_kernel_headers//include)%",
        "%package(@host_gcc8_glibc//include)%",
    ],
    host_system_name = "x86_64-unknown-linux-gnu",
    target_libc = "glibc_" + host_gcc8_bundle()["pkg_version"]["glibc"],
    target_system_name = "x86_64-unknown-linux-gnu",
    toolchain_identifier = "host_linux_gcc8",
)

From my understanding, the cxx_builtin_include_directories defines a list of strings to serve as the --sysroot option passed to GCC as detailed in https://docs.bazel.build/versions/0.23.0/skylark/lib/cc_common.html These strings are in the format %sysroot%.

Since package(@host_gcc8_toolchain//include/c++/8) for example, does not mean anything to GCC, bazel has to somehow expand this function to produce the actual path to the files included in the package before passing them to the compiler driver.

But how can it determine that this needs to be expanded and that it is not a regular string ? So how does Bazel preprocess the BUILD file ? Is it because of the % ... % pattern ? Where is this documented ?

is "%package(@external_package//target)%" a pattern that can be used elsewhere ? In any BUILD file ? Where do I find Bazel documentation showing how this works ?

Answer 1

These directives are expanded by cc_common.create_cc_toolchain_config_info within the cc_toolchain_config rule implementation not any sort of preprocessing on the BUILD file (I.e., "%package(@host_gcc8_glibc//include)%" is literally passed into the cc_toolchain_config rule.) I'm not aware that these special expansions are completely documented anywhere but the source.