Bazel: Linkopts Not Propagated Without Srcs?

Hey everyone! Let's dive into a peculiar issue in Bazel that can trip you up when working with cc_library rules. It's about how linkopts behave when your library doesn't have any source files (srcs). So, if you've encountered linker errors that seem to defy logic, you're in the right place. We'll break down the problem, explore why it happens, and show you how to fix it.

Understanding the Problem

At its core, the issue is that linkopts defined in a cc_library rule might not be propagated to dependent targets if the library doesn't have any source files specified in the srcs attribute. This can lead to linker errors during the linking phase, especially when dealing with external libraries. Let's illustrate this with an example:

cc_library(
 name = "example_lib",
 linkopts = ["-lexample_link_lib"], # Specifies an external library to link against
)

cc_library(
 name = "dependent_lib",
 deps = [":example_lib"], # Depends on example_lib
)

In this scenario, example_lib declares a dependency on an external library using linkopts = ["-lexample_link_lib"]. The intention is that any target depending on example_lib should also link against this external library. However, if example_lib doesn't have any srcs files, the linkopts might not be correctly propagated to dependent_lib. This can manifest as linker errors, such as "undefined symbol" errors, because the symbols provided by example_link_lib are not being included in the final link.

Diving Deeper into Linkopts and Their Role

To truly grasp this issue, it's essential to understand what linkopts are and why they matter in the context of Bazel. linkopts are essentially flags passed directly to the linker during the linking stage of the build process. They are crucial when you need to incorporate external libraries, specify custom linking behavior, or handle special linking requirements that aren't covered by Bazel's default settings.

Think of linkopts as the instructions you give to the linker, telling it exactly which external libraries to include, where to find them, and how to handle them. Without the correct linkopts, the linker might miss essential pieces of your program, resulting in those dreaded "undefined symbol" errors. These errors occur when the linker encounters a function or variable that's used in your code but can't find its definition in any of the linked libraries. So, ensuring that linkopts are correctly propagated is vital for a successful build.

The Curious Case of Missing Source Files

Now, why does the presence or absence of source files in a cc_library affect linkopts propagation? This is where the inner workings of Bazel's build graph come into play. Bazel optimizes the build process by only rebuilding targets when their inputs change. In the case of a cc_library without srcs, Bazel might not consider it a significant target for certain build actions, including the propagation of linkopts. It's as if Bazel assumes that a library without source code is merely a placeholder and doesn't need the same level of attention during the linking phase.

This optimization, while generally beneficial, can lead to the problem we're discussing. When example_lib has no source files, Bazel might not create the necessary link actions to include the linkopts for downstream dependencies. This is a subtle but significant detail that can cause headaches if you're not aware of it. The lack of source files essentially makes the cc_library a less visible participant in the build process, and its linkopts can inadvertently get lost in the shuffle. So, the key takeaway here is that the presence of srcs acts as a signal to Bazel to treat the cc_library as a fully-fledged component that requires proper linking, including the propagation of linkopts.

Identifying the Trigger Conditions

The tricky part about this issue is that it doesn't always manifest itself. You might have cc_library rules without srcs that seem to work fine, while others cause linker errors. This inconsistency can make it challenging to diagnose the problem. The trigger conditions depend on a variety of factors, including:

• The specific linker being used (e.g., ld.lld, GNU ld).
• The order of libraries in the link command.
• The presence of other dependencies and their linkopts.
• The nature of the external library being linked.

In essence, the issue is more likely to surface when the symbols provided by the external library are needed early in the linking process. If the linker encounters a reference to a symbol from example_link_lib before it has processed the library itself, it will report an "undefined symbol" error. However, if the symbol is referenced later, or if other libraries happen to pull in the necessary definitions, the problem might be masked.

This variability underscores the importance of understanding the underlying issue and adopting a consistent approach to ensure that linkopts are always propagated correctly.

Reproducing the Bug

To reproduce this bug, you'll need a Bazel project with the following structure:

1. A cc_library (e.g., example_lib) that defines linkopts but has no srcs.
2. An external library (e.g., libexample_link_lib.so) that provides some symbols.
3. Another cc_library (e.g., dependent_lib) that depends on the first library and uses symbols from the external library.
4. A cc_binary or cc_test that depends on the second library.

Here's a minimal example:

# BUILD file

cc_library(
 name = "example_lib",
 linkopts = ["-lexample_link_lib"],
 # no srcs here!
)

cc_library(
 name = "dependent_lib",
 deps = [":example_lib"],
 srcs = ["dependent_lib.cc"],
)

cc_binary(
 name = "my_binary",
 deps = [":dependent_lib"],
 srcs = ["my_binary.cc"],
)

// dependent_lib.cc
#include <iostream>

extern void example_function(); // Declared in libexample_link_lib.so

void dependent_function() {
 example_function();
 std::cout << "Dependent function called" << std::endl;
}

// my_binary.cc
void dependent_function();

int main() {
 dependent_function();
 return 0;
}

You'll also need to create a dummy libexample_link_lib.so library. Compile this setup with Bazel, and you should encounter a linker error similar to the following:

clang failed: error executing CppLink command
... ld.lld: error: undefined symbol: example_function

This error confirms that the linkopts from example_lib were not propagated to my_binary, resulting in the linker being unable to find the definition of example_function.

The Solution: Adding a Dummy Source File

The simplest and most reliable workaround for this issue is to add a dummy source file to the cc_library that defines the linkopts. This can be an empty .c or .cc file. By including a source file, you ensure that Bazel treats the library as a proper build target and correctly propagates the linkopts.

Here's how you can modify the example above:

1. Create an empty file named empty.cc.
2. Modify the BUILD file to include empty.cc in the srcs attribute of example_lib:

cc_library(
 name = "example_lib",
 linkopts = ["-lexample_link_lib"],
 srcs = ["empty.cc"], # Added a dummy source file
)

With this change, Bazel will now correctly propagate the linkopts, and the linker error should disappear. This solution is effective because it signals to Bazel that the cc_library is a complete target that requires proper linking, including the specified linkopts.

Why This Works: A Closer Look

Adding a dummy source file might seem like a trivial fix, but it has a significant impact on how Bazel processes the cc_library. When a cc_library has source files, Bazel creates a compilation action for it. This compilation action, even if it's just compiling an empty file, ensures that the library is treated as a regular build target. As a result, Bazel will correctly propagate the linkopts to any dependent targets.

The presence of a source file essentially forces Bazel to recognize the cc_library as a legitimate component in the build graph. This, in turn, triggers the necessary mechanisms for linkopts propagation. It's a small change with a big impact, ensuring that your linker gets the instructions it needs to incorporate external libraries correctly.

Best Practices and Recommendations

To avoid this issue in your Bazel projects, here are some best practices and recommendations:

1. Always include a source file in cc_library rules that define linkopts, even if it's just a dummy file. This ensures that the linkopts are correctly propagated.
2. Consider using cc_import for pre-built libraries. If you're linking against a pre-built library, cc_import might be a more appropriate rule than cc_library. cc_import is designed specifically for importing pre-compiled artifacts and handles linking more explicitly.
3. Be mindful of the dependencies in your build graph. Ensure that dependencies are correctly declared and that linkopts are being propagated as expected. Use Bazel's query tools to inspect the build graph and verify dependencies.
4. Test your builds thoroughly. Linker errors can be subtle and might not surface until late in the development cycle. Regular testing, especially in different build configurations, can help catch these issues early.

When to Use cc_import Instead

While adding a dummy source file is a reliable workaround, it's worth considering whether cc_library is the right rule for your use case. If you're working with pre-built libraries (e.g., .so or .a files), cc_import might be a better fit. cc_import is specifically designed for importing pre-compiled artifacts into your Bazel build.

Here's how you can use cc_import:

cc_import(
 name = "example_link_lib_import",
 shared_library = "libexample_link_lib.so",
)

cc_library(
 name = "dependent_lib",
 deps = [":example_link_lib_import"],
 srcs = ["dependent_lib.cc"],
)

With cc_import, you explicitly declare the pre-built library, and Bazel handles the linking process more directly. This approach can be cleaner and more robust than relying on linkopts in a cc_library without srcs. cc_import also makes it clearer that you're importing an external dependency, which can improve the readability and maintainability of your build files.

Conclusion

The issue of linkopts not being propagated in cc_library rules without srcs can be a frustrating stumbling block in Bazel. However, by understanding the underlying cause and applying the solutions discussed, you can avoid this pitfall and ensure that your builds link correctly. Remember to always include a source file or consider using cc_import for pre-built libraries. Keep these tips in mind, and you'll be well-equipped to tackle any linker errors that come your way. Happy building, folks!