This page describes how to integrate with C++ rules on various levels.
Accessing the C++ toolchain
You should use the helper functions available at
@rules_cc//cc:find_cc_toolchain.bzl
to depend on a CC toolchain from a Starlark rule.
To depend on a C++ toolchain in your rule, set the toolchains
parameter to
use_cc_toolchain()
. Then, in the rule implementation, use
find_cpp_toolchain(ctx)
to get the
CcToolchainInfo
. A complete working
example can be found in the rules_cc
examples.
Generating command lines and environment variables using the C++ toolchain
Typically, you would integrate with the C++ toolchain to have the same command line flags as C++ rules do, but without using C++ actions directly. This is because when writing our own actions, they must behave consistently with the C++ toolchain - for example, passing C++ command line flags to a tool that invokes the C++ compiler behind the scenes.
C++ rules use a special way of constructing command lines based on feature configuration. To construct a command line, you need the following:
features
andaction_configs
- these come from theCcToolchainConfigInfo
and encapsulated inCcToolchainInfo
FeatureConfiguration
- returned by cc_common.configure_features- cc toolchain config variables - returned by cc_common.create_compile_variables or cc_common.create_link_variables.
There still are tool-specific getters, such as
compiler_executable.
Prefer get_tool_for_action
over these, as tool-specific getters will
eventually be removed.
A complete working example can be found in the rules_cc examples.
Implementing Starlark rules that depend on C++ rules and/or that C++ rules can depend on
Most C++ rules provide
CcInfo
,
a provider containing CompilationContext
and
LinkingContext
.
Through these it is possible to access information such as all transitive headers
or libraries to link. From CcInfo
and from the CcToolchainInfo
custom
Starlark rules should be able to get all the information they need.
If a custom Starlark rule provides CcInfo
, it's a signal to the C++ rules that
they can also depend on it. Be careful, however - if you only need to propagate
CcInfo
through the graph to the binary rule that then makes use of it, wrap
CcInfo
in a different provider. For example, if java_library
rule wanted
to propagate native dependencies up to the java_binary
, it shouldn't provide
CcInfo
directly (cc_binary
depending on java_library
doesn't make sense),
it should wrap it in, for example, JavaCcInfo
.
A complete working example can be found in the rules_cc examples.
Reusing logic and actions of C++ rules
Not stable yet; This section will be updated once the API stabilizes. Follow #4570 for up-to-date information.