rules_cc_hdrs_map
v0.20.1
published 1 week ago
6 stars
0 forks
2 watchers
AleksanderGondek/rules_cc_hdrs_map
GNU General Public License v3.0
public
1 assets
5 downloads
64 KB
Maintained byAleksander Gondek
Escape weird includes path hell with header maps
v0.20.1
August 8, 2025
[expand for release notes]

rules_cc_hdrs_map

ci

This project extends Bazel CC build capabilities with headers map implementation (allowing for easy support for most bizzare include path schemes).

In addition, it exposes CC compilation and linking functions in form of Bazel subrules.

See examples for how to use rules_cc_hdrs_map (and why).

Shortest possible example

$ cat foo.hpp
const std::string GREETINGS = "Hello";

$ cat foo.cpp
#include "bar/foo.h"
...

$ cat BUILD.bazel
load("@rules_cc_hdrs_map//cc_hdrs_map:defs.bzl", "cc_bin")

cc_bin(
    name = "foo",
    srcs = [
        "foo.cpp",
        "foo.hpp",
    ],
    hdrs_map = {
        "**/foo.hpp": ["bar/{filename}"],
    }
)

Table of contents

  1. What issue is being addressed?
  2. How the issue is being addressed?
  3. What issue is being addressed?
  4. Rules
    1. cc_archive
    2. cc_bin
    3. cc_hdrs
    4. cc_so
  5. HdrsMapInfo provider

What issue is being addressed?

Creation of arbitrary include paths from existing sources.

Scenario: we want to build a C/CPP codebase with Bazel.

One of its key characteristics is that most of the include statements do not reflect the code structure in the project - for example, header file located under path “name/a.hpp” is never included as “name/a.hpp”, instead an arbitrary list of aliases is used in the code (“x/y/z/a.hpp”, “b.hpp” etc.). There is no overarching convention that could be used to generalize those statements into another file file hierarchy - in other words, every header file is a special case of its own.

Unfortunately we are forbidden from modifying the code itself and the directory structure (hello from enterprise word).

As Bazel rules_cc have the expectation of header files being included in a way that resembles the file structure in the WORKSPACE (and one can only provide single “include prefix” per library), we need to prepare the “expected file structure” before passing them into the rules_cc.

In the most naive approach, said “expected file structure” is being prepared for each compilable target (copying over files), passing on the already created structure to targets that depend on it. Very quickly conflicts occur and change of a single header file may cascade into rebuilding hundreds of targets.

There has to be a better way!

How the issue is being addressed?

The concept of header map is introduced - it is a dictionary, containing mapping between simple glob paths and their desired include paths. For example: “**/a.hpp”: “x/y/z/a.hpp” expresses the intent to import any header file with name “a.hpp”, present during compilation , as “x/y/z/a.hpp”.

Said header map is propagated across all compatible C/C++ rules (meaning those from this WORKSPACE) and is being merged with all other header maps present.

No action is being performed up until the moment of compilation - header mappings, resulting from the header map dictionary, are created only for the purposes of compilation and are NOT part of any rule output. This ensures the impact for the Bazel cache is minimal and the compatibility with original rules_cc.

cc_archive

load("@rules_cc_hdrs_map//cc_hdrs_map:defs.bzl", "cc_archive")

cc_archive(name, deps, srcs, data, hdrs, additional_compiler_inputs, additional_linker_inputs,
           archive_lib_name, conlyopts, copts, cxxopts, defines, dynamic_deps, hdrs_map,
           implementation_deps, implementation_hdrs, include_prefix, includes, linkopts, linkshared,
           linkstamp, linkstatic, local_defines, module_interfaces, nocopts, reexport_deps,
           strip_include_prefix, textual_hdrs, win_def_file)

Produce an archive file.

The intended major difference between this rule and rules_cc's cc_static_library, is that this rule does not intend to pull-in all static dependencies.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps The list of dependencies of current target List of labels optional []
srcs The list of source files. List of labels required
data The list of files needed by this target at runtime. See general comments about data at Typical attributes defined by most build rules. List of labels optional []
hdrs List of headers that may be included by dependent rules transitively. Notice: the cutoff happens during compilation. List of labels optional []
additional_compiler_inputs Any additional files you might want to pass to the compiler command line, such as sanitizer ignorelists, for example. Files specified here can then be used in copts with the $(location) function. List of labels optional []
additional_linker_inputs Any additional files that you may want to pass to the linker, for example, linker scripts. You have to separately pass any linker flags that the linker needs in order to be aware of this file. You can do so via the linkopts attribute. List of labels optional []
archive_lib_name Specify the name of the created .a file (that is decoupled from the rule instance name). Note, that the 'cc_archive' is opinionated and will remove any leading 'lib' prefix and any '.a' in the name (meaning 'libTest.a.x64.a' will become 'Test.x64' and will produce 'libTest.x64.a') String optional ""
conlyopts Add these options to the C compilation command. Subject to "Make variable" substitution and Bourne shell tokenization. List of strings optional []
copts Add these options to the C++ compilation command. Subject to "Make variable" substitution and Bourne shell tokenization. Each string in this attribute is added in the given order to COPTS before compiling the binary target. The flags take effect only for compiling this target, not its dependencies, so be careful about header files included elsewhere. All paths should be relative to the workspace, not to the current package.

If the package declares the feature no_copts_tokenization, Bourne shell tokenization applies only to strings that consist of a single "Make" variable.		 List of strings optional []
cxxopts Add these options to the C++ compilation command. Subject to "Make variable" substitution and Bourne shell tokenization. List of strings optional []
defines List of defines to add to the compile line. Subject to "Make" variable substitution and Bourne shell tokenization. Each string, which must consist of a single Bourne shell token, is prepended with -D and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects. When in doubt, add define values to local_defines instead. List of strings optional []
dynamic_deps In contrast to rules_cc, the dynamic_deps of rules_cc_hdrs_map are simply translated into deps parameter, and the providers (CcInfo vs CcSharedInfo) are used to steer the behavior further. List of labels optional []
hdrs_map Dictionary describing paths under which header files should be avaiable as.

Keys are simple glob pathnames, used to match agains all header files avaiable in the rule. Values are list of paths to which matching header files should be mapped.

'{filename}' is special token used to signify to matching file name.

For example: '"**/*o.hpp": ["a/{filename}"]' - will ensure all hpp files with names ending with '0' will be also avaible as if they were placed in a subdirectory.		 Dictionary: String -> List of strings optional {}
implementation_deps The list of other libraries that the library target depends on. Unlike with deps, the headers and include paths of these libraries (and all their transitive deps) are only used for compilation of this library, and not libraries that depend on it. Libraries specified with implementation_deps are still linked in binary targets that depend on this library. List of labels optional []
implementation_hdrs List of headers that CANNOT be included by dependent rules. Notice: the cutoff happens during compilation. List of labels optional []
include_prefix The prefix to add to the paths of the headers of this rule. When set, the headers in the hdrs attribute of this rule are accessible at is the value of this attribute prepended to their repository-relative path.

The prefix in the strip_include_prefix attribute is removed before this prefix is added.		 String optional ""
includes List of include dirs to be added to the compile line. Subject to "Make variable" substitution. Each string is prepended with -isystem and added to COPTS. Unlike COPTS, these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to COPTS instead.

Headers must be added to srcs or hdrs, otherwise they will not be available to dependent rules when compilation is sandboxed (the default).		 List of strings optional []
linkopts Add these flags to the C++ linker command. Subject to "Make" variable substitution, Bourne shell tokenization and label expansion. Each string in this attribute is added to LINKOPTS before linking the binary target. Each element of this list that does not start with $ or - is assumed to be the label of a target in deps. The list of files generated by that target is appended to the linker options. An error is reported if the label is invalid, or is not declared in deps. List of strings optional []
linkshared Create a shared library. To enable this attribute, include linkshared=True in your rule. By default this option is off. Boolean optional False
linkstamp Simultaneously compiles and links the specified C++ source file into the final binary. This trickery is required to introduce timestamp information into binaries; if we compiled the source file to an object file in the usual way, the timestamp would be incorrect. A linkstamp compilation may not include any particular set of compiler flags and so should not depend on any particular header, compiler option, or other build variable. This option should only be needed in the base package. Label optional None
linkstatic If enabled and this is a binary or test, this option tells the build tool to link in .a's instead of .so's for user libraries whenever possible. System libraries such as libc (but not the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only mostly static. The linkstatic attribute has a different meaning if used on a cc_library() rule. For a C++ library, linkstatic=True indicates that only static linking is allowed, so no .so will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. Boolean optional False
local_defines List of defines to add to the compile line. Subject to "Make" variable substitution and Bourne shell tokenization. Each string, which must consist of a single Bourne shell token, is prepended with -D and added to the compile command line for this target, but not to its dependents. List of strings optional []
module_interfaces The list of files that are regarded as C++20 Modules Interface.

C++ Standard has no restriction about module interface file extension * Clang use cppm * GCC can use any source file extension * MSVC use ixx

The use is guarded by the flag --experimental_cpp_modules.		 List of labels optional []
nocopts Remove matching options from the C++ compilation command. Subject to "Make" variable substitution. The value of this attribute is interpreted as a regular expression. Any preexisting COPTS that match this regular expression (including values explicitly specified in the rule's copts attribute) will be removed from COPTS for purposes of compiling this rule. This attribute should not be needed or used outside of third_party. The values are not preprocessed in any way other than the "Make" variable substitution. String optional ""
reexport_deps - List of labels optional []
strip_include_prefix The prefix to strip from the paths of the headers of this rule. When set, the headers in the hdrs attribute of this rule are accessible at their path with this prefix cut off.

If it's a relative path, it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path.

The prefix in the include_prefix attribute is added after this prefix is stripped.		 String optional ""
textual_hdrs The list of header files published by this library to be textually included by sources in dependent rules.

This is the location for declaring header files that cannot be compiled on their own; that is, they always need to be textually included by other source files to build valid code.		 List of labels optional []
win_def_file The Windows DEF file to be passed to linker.

This attribute should only be used when Windows is the target platform. It can be used to export symbols during linking a shared library.		 Label optional None

cc_bin

load("@rules_cc_hdrs_map//cc_hdrs_map:defs.bzl", "cc_bin")

cc_bin(name, deps, srcs, data, hdrs, additional_compiler_inputs, additional_linker_inputs,
       conlyopts, copts, cxxopts, defines, dynamic_deps, hdrs_map, includes, link_extra_lib, linkopts,
       linkshared, linkstatic, local_defines, malloc, module_interfaces, nocopts, reexport_deps,
       stamp, win_def_file)

Produce exectuable binary.

It is intended for this rule, to differ from rules_cc's cc_binary in the following fashion: it aims to automatically gather all of its dynamic dependencies and make them available during binary execution.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps The list of dependencies of current target List of labels optional []
srcs The list of source files. List of labels required
data The list of files needed by this target at runtime. See general comments about data at Typical attributes defined by most build rules. List of labels optional []
hdrs List of headers that may be included by dependent rules transitively. Notice: the cutoff happens during compilation. List of labels optional []
additional_compiler_inputs Any additional files you might want to pass to the compiler command line, such as sanitizer ignorelists, for example. Files specified here can then be used in copts with the $(location) function. List of labels optional []
additional_linker_inputs Any additional files that you may want to pass to the linker, for example, linker scripts. You have to separately pass any linker flags that the linker needs in order to be aware of this file. You can do so via the linkopts attribute. List of labels optional []
conlyopts Add these options to the C compilation command. Subject to "Make variable" substitution and Bourne shell tokenization. List of strings optional []
copts Add these options to the C++ compilation command. Subject to "Make variable" substitution and Bourne shell tokenization. Each string in this attribute is added in the given order to COPTS before compiling the binary target. The flags take effect only for compiling this target, not its dependencies, so be careful about header files included elsewhere. All paths should be relative to the workspace, not to the current package.

If the package declares the feature no_copts_tokenization, Bourne shell tokenization applies only to strings that consist of a single "Make" variable.		 List of strings optional []
cxxopts Add these options to the C++ compilation command. Subject to "Make variable" substitution and Bourne shell tokenization. List of strings optional []
defines List of defines to add to the compile line. Subject to "Make" variable substitution and Bourne shell tokenization. Each string, which must consist of a single Bourne shell token, is prepended with -D and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects. When in doubt, add define values to local_defines instead. List of strings optional []
dynamic_deps In contrast to rules_cc, the dynamic_deps of rules_cc_hdrs_map are simply translated into deps parameter, and the providers (CcInfo vs CcSharedInfo) are used to steer the behavior further. List of labels optional []
hdrs_map Dictionary describing paths under which header files should be avaiable as.

Keys are simple glob pathnames, used to match agains all header files avaiable in the rule. Values are list of paths to which matching header files should be mapped.

'{filename}' is special token used to signify to matching file name.

For example: '"**/*o.hpp": ["a/{filename}"]' - will ensure all hpp files with names ending with '0' will be also avaible as if they were placed in a subdirectory.		 Dictionary: String -> List of strings optional {}
includes List of include dirs to be added to the compile line. Subject to "Make variable" substitution. Each string is prepended with -isystem and added to COPTS. Unlike COPTS, these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to COPTS instead.

Headers must be added to srcs or hdrs, otherwise they will not be available to dependent rules when compilation is sandboxed (the default).		 List of strings optional []
link_extra_lib Control linking of extra libraries.

By default, C++ binaries are linked against //tools/cpp:link_extra_lib, which by default depends on the label flag //tools/cpp:link_extra_libs. Without setting the flag, this library is empty by default. Setting the label flag allows linking optional dependencies, such as overrides for weak symbols, interceptors for shared library functions, or special runtime libraries (for malloc replacements, prefer malloc or --custom_malloc). Setting this attribute to None disables this behaviour.		 Label optional None
linkopts Add these flags to the C++ linker command. Subject to "Make" variable substitution, Bourne shell tokenization and label expansion. Each string in this attribute is added to LINKOPTS before linking the binary target. Each element of this list that does not start with $ or - is assumed to be the label of a target in deps. The list of files generated by that target is appended to the linker options. An error is reported if the label is invalid, or is not declared in deps. List of strings optional []
linkshared Create a shared library. To enable this attribute, include linkshared=True in your rule. By default this option is off. Boolean optional False
linkstatic If enabled and this is a binary or test, this option tells the build tool to link in .a's instead of .so's for user libraries whenever possible. System libraries such as libc (but not the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only mostly static. The linkstatic attribute has a different meaning if used on a cc_library() rule. For a C++ library, linkstatic=True indicates that only static linking is allowed, so no .so will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. Boolean optional False
local_defines List of defines to add to the compile line. Subject to "Make" variable substitution and Bourne shell tokenization. Each string, which must consist of a single Bourne shell token, is prepended with -D and added to the compile command line for this target, but not to its dependents. List of strings optional []
malloc Override the default dependency on malloc.

By default, C++ binaries are linked against //tools/cpp:malloc, which is an empty library so the binary ends up using libc malloc. This label must refer to a cc_library. If compilation is for a non-C++ rule, this option has no effect. The value of this attribute is ignored if linkshared=True is specified.		 Label optional None
module_interfaces The list of files that are regarded as C++20 Modules Interface.

C++ Standard has no restriction about module interface file extension * Clang use cppm * GCC can use any source file extension * MSVC use ixx

The use is guarded by the flag --experimental_cpp_modules.		 List of labels optional []
nocopts Remove matching options from the C++ compilation command. Subject to "Make" variable substitution. The value of this attribute is interpreted as a regular expression. Any preexisting COPTS that match this regular expression (including values explicitly specified in the rule's copts attribute) will be removed from COPTS for purposes of compiling this rule. This attribute should not be needed or used outside of third_party. The values are not preprocessed in any way other than the "Make" variable substitution. String optional ""
reexport_deps - List of labels optional []
stamp Whether to encode build information into the binary. Possible values:

* stamp = 1: Always stamp the build information into the binary, even in --nostamp builds. This setting should be avoided, since it potentially kills remote caching for the binary and any downstream actions that depend on it.

* stamp = 0: Always replace build information by constant values. This gives good build result caching.

* stamp = -1: Embedding of build information is controlled by the --[no]stamp flag.

Stamped binaries are not rebuilt unless their dependencies change.		 Integer optional -1
win_def_file The Windows DEF file to be passed to linker.

This attribute should only be used when Windows is the target platform. It can be used to export symbols during linking a shared library.		 Label optional None

cc_hdrs

load("@rules_cc_hdrs_map//cc_hdrs_map:defs.bzl", "cc_hdrs")

cc_hdrs(name, deps, data, hdrs, hdrs_map, implementation_hdrs, module_interfaces, win_def_file)

Define header files properties.

This rule groups headers into a singular target and allows to attach 'include_path' modifications information to them, so that wherever the header files are being used, they can be used with their intended include paths.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps The list of dependencies of current target List of labels optional []
data The list of files needed by this target at runtime. See general comments about data at Typical attributes defined by most build rules. List of labels optional []
hdrs List of headers that may be included by dependent rules transitively. Notice: the cutoff happens during compilation. List of labels optional []
hdrs_map Dictionary describing paths under which header files should be avaiable as.

Keys are simple glob pathnames, used to match agains all header files avaiable in the rule. Values are list of paths to which matching header files should be mapped.

'{filename}' is special token used to signify to matching file name.

For example: '"**/*o.hpp": ["a/{filename}"]' - will ensure all hpp files with names ending with '0' will be also avaible as if they were placed in a subdirectory.		 Dictionary: String -> List of strings optional {}
implementation_hdrs List of headers that CANNOT be included by dependent rules. Notice: the cutoff happens during compilation. List of labels optional []
module_interfaces The list of files that are regarded as C++20 Modules Interface.

C++ Standard has no restriction about module interface file extension * Clang use cppm * GCC can use any source file extension * MSVC use ixx

The use is guarded by the flag --experimental_cpp_modules.		 List of labels optional []
win_def_file The Windows DEF file to be passed to linker.

This attribute should only be used when Windows is the target platform. It can be used to export symbols during linking a shared library.		 Label optional None

cc_so

load("@rules_cc_hdrs_map//cc_hdrs_map:defs.bzl", "cc_so")

cc_so(name, deps, srcs, data, hdrs, additional_compiler_inputs, additional_linker_inputs,
      alwayslink, conlyopts, copts, cxxopts, defines, dynamic_deps, exports_filter, hdrs_map,
      implementation_deps, implementation_hdrs, include_prefix, includes, link_extra_lib, linkopts,
      linkshared, linkstamp, linkstatic, local_defines, malloc, module_interfaces, nocopts, roots,
      shared_lib_name, strip_include_prefix, textual_hdrs, win_def_file)

Produce shared object library.

The intended difference between this rule and the rules_cc's cc_shared_library is to:

  1. remove 'cc_library' out of the equation (no more targets that produce either archive or sol)
  2. unify handling of dependencies that are equipped with CcInfo and CcSharedLibraryInfo (use singular attribute of deps to track them both).

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps The list of dependencies of current target List of labels optional []
srcs The list of source files. List of labels required
data The list of files needed by this target at runtime. See general comments about data at Typical attributes defined by most build rules. List of labels optional []
hdrs List of headers that may be included by dependent rules transitively. Notice: the cutoff happens during compilation. List of labels optional []
additional_compiler_inputs Any additional files you might want to pass to the compiler command line, such as sanitizer ignorelists, for example. Files specified here can then be used in copts with the $(location) function. List of labels optional []
additional_linker_inputs Any additional files that you may want to pass to the linker, for example, linker scripts. You have to separately pass any linker flags that the linker needs in order to be aware of this file. You can do so via the linkopts attribute. List of labels optional []
alwayslink If 1, any binary that depends (directly or indirectly) on this C++ precompiled library will link in all the object files archived in the static library, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary, e.g., if your code registers to receive some callback provided by some service. Boolean optional False
conlyopts Add these options to the C compilation command. Subject to "Make variable" substitution and Bourne shell tokenization. List of strings optional []
copts Add these options to the C++ compilation command. Subject to "Make variable" substitution and Bourne shell tokenization. Each string in this attribute is added in the given order to COPTS before compiling the binary target. The flags take effect only for compiling this target, not its dependencies, so be careful about header files included elsewhere. All paths should be relative to the workspace, not to the current package.

If the package declares the feature no_copts_tokenization, Bourne shell tokenization applies only to strings that consist of a single "Make" variable.		 List of strings optional []
cxxopts Add these options to the C++ compilation command. Subject to "Make variable" substitution and Bourne shell tokenization. List of strings optional []
defines List of defines to add to the compile line. Subject to "Make" variable substitution and Bourne shell tokenization. Each string, which must consist of a single Bourne shell token, is prepended with -D and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects. When in doubt, add define values to local_defines instead. List of strings optional []
dynamic_deps In contrast to rules_cc, the dynamic_deps of rules_cc_hdrs_map are simply translated into deps parameter, and the providers (CcInfo vs CcSharedInfo) are used to steer the behavior further. List of labels optional []
exports_filter This attribute contains a list of targets that are claimed to be exported by the current shared library.

Any target deps is already understood to be exported by the shared library. This attribute should be used to list any targets that are exported by the shared library but are transitive dependencies of deps.

Note that this attribute is not actually adding a dependency edge to those targets, the dependency edge should instead be created by deps.The entries in this attribute are just strings. Keep in mind that when placing a target in this attribute, this is considered a claim that the shared library exports the symbols from that target. The cc_shared_library logic doesn't actually handle telling the linker which symbols should be exported.

The following syntax is allowed:

//foo:pkg to account for any target in foo/BUILD

//foo:subpackages to account for any target in foo/BUILD or any other package below foo/ like foo/bar/BUILD		 List of strings optional []
hdrs_map Dictionary describing paths under which header files should be avaiable as.

Keys are simple glob pathnames, used to match agains all header files avaiable in the rule. Values are list of paths to which matching header files should be mapped.

'{filename}' is special token used to signify to matching file name.

For example: '"**/*o.hpp": ["a/{filename}"]' - will ensure all hpp files with names ending with '0' will be also avaible as if they were placed in a subdirectory.		 Dictionary: String -> List of strings optional {}
implementation_deps The list of other libraries that the library target depends on. Unlike with deps, the headers and include paths of these libraries (and all their transitive deps) are only used for compilation of this library, and not libraries that depend on it. Libraries specified with implementation_deps are still linked in binary targets that depend on this library. List of labels optional []
implementation_hdrs List of headers that CANNOT be included by dependent rules. Notice: the cutoff happens during compilation. List of labels optional []
include_prefix The prefix to add to the paths of the headers of this rule. When set, the headers in the hdrs attribute of this rule are accessible at is the value of this attribute prepended to their repository-relative path.

The prefix in the strip_include_prefix attribute is removed before this prefix is added.		 String optional ""
includes List of include dirs to be added to the compile line. Subject to "Make variable" substitution. Each string is prepended with -isystem and added to COPTS. Unlike COPTS, these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to COPTS instead.

Headers must be added to srcs or hdrs, otherwise they will not be available to dependent rules when compilation is sandboxed (the default).		 List of strings optional []
link_extra_lib Control linking of extra libraries.

By default, C++ binaries are linked against //tools/cpp:link_extra_lib, which by default depends on the label flag //tools/cpp:link_extra_libs. Without setting the flag, this library is empty by default. Setting the label flag allows linking optional dependencies, such as overrides for weak symbols, interceptors for shared library functions, or special runtime libraries (for malloc replacements, prefer malloc or --custom_malloc). Setting this attribute to None disables this behaviour.		 Label optional None
linkopts Add these flags to the C++ linker command. Subject to "Make" variable substitution, Bourne shell tokenization and label expansion. Each string in this attribute is added to LINKOPTS before linking the binary target. Each element of this list that does not start with $ or - is assumed to be the label of a target in deps. The list of files generated by that target is appended to the linker options. An error is reported if the label is invalid, or is not declared in deps. List of strings optional []
linkshared Create a shared library. To enable this attribute, include linkshared=True in your rule. By default this option is off. Boolean optional False
linkstamp Simultaneously compiles and links the specified C++ source file into the final binary. This trickery is required to introduce timestamp information into binaries; if we compiled the source file to an object file in the usual way, the timestamp would be incorrect. A linkstamp compilation may not include any particular set of compiler flags and so should not depend on any particular header, compiler option, or other build variable. This option should only be needed in the base package. Label optional None
linkstatic If enabled and this is a binary or test, this option tells the build tool to link in .a's instead of .so's for user libraries whenever possible. System libraries such as libc (but not the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only mostly static. The linkstatic attribute has a different meaning if used on a cc_library() rule. For a C++ library, linkstatic=True indicates that only static linking is allowed, so no .so will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. Boolean optional False
local_defines List of defines to add to the compile line. Subject to "Make" variable substitution and Bourne shell tokenization. Each string, which must consist of a single Bourne shell token, is prepended with -D and added to the compile command line for this target, but not to its dependents. List of strings optional []
malloc Override the default dependency on malloc.

By default, C++ binaries are linked against //tools/cpp:malloc, which is an empty library so the binary ends up using libc malloc. This label must refer to a cc_library. If compilation is for a non-C++ rule, this option has no effect. The value of this attribute is ignored if linkshared=True is specified.		 Label optional None
module_interfaces The list of files that are regarded as C++20 Modules Interface.

C++ Standard has no restriction about module interface file extension * Clang use cppm * GCC can use any source file extension * MSVC use ixx

The use is guarded by the flag --experimental_cpp_modules.		 List of labels optional []
nocopts Remove matching options from the C++ compilation command. Subject to "Make" variable substitution. The value of this attribute is interpreted as a regular expression. Any preexisting COPTS that match this regular expression (including values explicitly specified in the rule's copts attribute) will be removed from COPTS for purposes of compiling this rule. This attribute should not be needed or used outside of third_party. The values are not preprocessed in any way other than the "Make" variable substitution. String optional ""
roots (Not yet implemented) List of labels optional []
shared_lib_name Specify the name of the created SOL file (that is decoupled from the rule instance name). Note, that the 'cc_so' is opinionated and will remove any leading 'lib' prefix and any '.so' in the name (meaning 'libTest.so.x64.so' will become 'Test.x64' and will produce 'libTest.x64.so') String optional ""
strip_include_prefix The prefix to strip from the paths of the headers of this rule. When set, the headers in the hdrs attribute of this rule are accessible at their path with this prefix cut off.

If it's a relative path, it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path.

The prefix in the include_prefix attribute is added after this prefix is stripped.		 String optional ""
textual_hdrs The list of header files published by this library to be textually included by sources in dependent rules.

This is the location for declaring header files that cannot be compiled on their own; that is, they always need to be textually included by other source files to build valid code.		 List of labels optional []
win_def_file The Windows DEF file to be passed to linker.

This attribute should only be used when Windows is the target platform. It can be used to export symbols during linking a shared library.		 Label optional None

HdrsMapInfo

load("@rules_cc_hdrs_map//cc_hdrs_map:defs.bzl", "HdrsMapInfo")

HdrsMapInfo(hdrs, implementation_hdrs, hdrs_map, deps)

Represents grouping of CC header files, alongsdie with their intended include paths.

FIELDS

Name Description
hdrs Headers which should be exposed after the compilation is done.
implementation_hdrs Headers that should not be propagated after the compilation.
hdrs_map (hdrs_map struct) object describing desired header file mappings
deps CcInfo/CcSharedLibraryInfo-aware dependencies that need to be propagated, for this provider to compile and link

actions.compile_kwargs

load("@rules_cc_hdrs_map//cc_hdrs_map:defs.bzl", "actions")

actions.compile_kwargs(ctx, rule_attrs)

PARAMETERS

Name Description Default Value
ctx

-

none
rule_attrs

-

none

actions.link_to_archive_kwargs

load("@rules_cc_hdrs_map//cc_hdrs_map:defs.bzl", "actions")

actions.link_to_archive_kwargs(ctx, rule_attrs)

PARAMETERS

Name Description Default Value
ctx

-

none
rule_attrs

-

none

actions.link_to_binary_kwargs

load("@rules_cc_hdrs_map//cc_hdrs_map:defs.bzl", "actions")

actions.link_to_binary_kwargs(ctx, rule_attrs)

PARAMETERS

Name Description Default Value
ctx

-

none
rule_attrs

-

none

actions.link_to_so_kwargs

load("@rules_cc_hdrs_map//cc_hdrs_map:defs.bzl", "actions")

actions.link_to_so_kwargs(ctx, rule_attrs)

PARAMETERS

Name Description Default Value
ctx

-

none
rule_attrs

-

none

actions.prepare_for_compilation

load("@rules_cc_hdrs_map//cc_hdrs_map:defs.bzl", "actions")

actions.prepare_for_compilation(sctx, input_hdrs_map, input_hdrs, input_implementation_hdrs,
                                input_deps, input_includes)

Materialize information from hdrs map.

This function creates a epheremal directory, that contains all of the patterns specified within hdrs_map providers, thus making them all available under singular, temporary include statment.

PARAMETERS

Name Description Default Value
sctx subrule context none
input_hdrs_map list of HdrsMapInfo which should be used for materialization of compilation context none
input_hdrs direct headers provided to the action none
input_implementation_hdrs direct headers provided to the action none
input_deps dependencies specified for the action none
input_includes include statements specified for the action none

providers_helper.materialize_hdrs_mapping

load("@rules_cc_hdrs_map//cc_hdrs_map:defs.bzl", "providers_helper")

providers_helper.materialize_hdrs_mapping(invoker_label, actions, hdrs_map, hdrs)

Materialize the expected file hierarchy.

Creates the header file hierarchy accordingly to specifications in passed-in hdrs_map under 'vhm' directory.

PARAMETERS

Name Description Default Value
invoker_label label of rule invoking the method none
actions bazel ctx.actions none
hdrs_map HdrsMapInfo representing the headers mapping none
hdrs list of all header files that should be matched against the map none

RETURNS

(materialized_include_path, materialized_hdrs_files): tuple of include_path to the created header files dir and list of paths to all header files created.

providers_helper.merge_cc_shared_library_infos

load("@rules_cc_hdrs_map//cc_hdrs_map:defs.bzl", "providers_helper")

providers_helper.merge_cc_shared_library_infos(targets, dynamic_deps, exports, linker_input,
                                               link_once_static_libs)

Merge CcSharedLibraryInfos from targets into singualr provider.

PARAMETERS

Name Description Default Value
targets list of Bazel targets that should be merged. They must contain either CcInfo or CcSharedLibraryInfo provider. []
dynamic_deps sequence of Depsets representing additional dynamic deps. None
exports cc_libraries that are linked statically and exported". None
linker_input the resultign linker inptu artifact for the shared library. None
link_once_static_libs all libraries linked statically into this library that should only be linked once. None

RETURNS

CcSharedLibraryInfo provider.

providers_helper.merge_hdrs_map_infos

load("@rules_cc_hdrs_map//cc_hdrs_map:defs.bzl", "providers_helper")

providers_helper.merge_hdrs_map_infos(targets, hdrs, implementation_hdrs, hdrs_map, hdrs_map_deps,
                                      pin_down_non_globs)

Merge all HdrsMapInfo providers from targets into singular one.

PARAMETERS

Name Description Default Value
targets

-

[]
hdrs additional header files to include, None
implementation_hdrs additional implementation headers to include, None
hdrs_map initial hdrs_map to use as a foundation for merge, None
hdrs_map_deps additional dependencies to include, None
pin_down_non_globs wheather the final hdrs_map should have its non_glob dependencies pinned. True

RETURNS

HdrsMapInfo provider that represents merge of all HdrsMapInfos from targets.

providers_helper.new_hdrs_map

load("@rules_cc_hdrs_map//cc_hdrs_map:defs.bzl", "providers_helper")

providers_helper.new_hdrs_map(from_dict, _glob, _non_glob)

Create new instance of HdrsMap struct.

PARAMETERS

Name Description Default Value
from_dict

-

{}
_glob

-

None
_non_glob

-

None

providers_helper.quotient_map_cc_shared_library_infos

load("@rules_cc_hdrs_map//cc_hdrs_map:defs.bzl", "providers_helper")

providers_helper.quotient_map_cc_shared_library_infos(targets, dynamic_deps, exports, linker_input,
                                                      link_once_static_libs)

Transform list of Bazel targets into CcSharedLibrayInfo attribue groups.

For given list of Bazel targets, attributes relating to CcSharedLibraryInfo (dynamic_deps, exports, linker_inputs, link_once_static_libs) will be extracted from said targets and the output will contain groups of that values.

PARAMETERS

Name Description Default Value
targets list of Bazel targets that should be mapped. They must contain either CcInfo or CcSharedLibraryInfo provider. []
dynamic_deps sequence of Depsets representing additional dynamic deps. None
exports cc_libraries that are linked statically and exported". None
linker_input the resultign linker inptu artifact for the shared library. None
link_once_static_libs all libraries linked statically into this library that should only be linked once. None

RETURNS

(dynamic_deps, exports, linker_inptuts, link_once_static_lib)

providers_helper.quotient_map_hdrs_map_infos

load("@rules_cc_hdrs_map//cc_hdrs_map:defs.bzl", "providers_helper")

providers_helper.quotient_map_hdrs_map_infos(targets, hdrs, implementation_hdrs, hdrs_map,
                                             hdrs_map_deps, traverse_deps)

Take all HdrsMapInfo key-values and group them by keys.

PARAMETERS

Name Description Default Value
targets

-

[]
hdrs additional header files to include, None
implementation_hdrs additional implementation headers to include, None
hdrs_map initial hdrs_map to use as a foundation for merge, None
hdrs_map_deps additional dependencies to include None
traverse_deps wheather to gather HdrsMapInfos transitvely True

RETURNS

(hdrs, implementation_hdrs, hdrs_map, hdr_maps_deps): tuple