The Build Registry

rules_cc_hdrs_map

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}"],
    }
)

What issue is being addressed?
How the issue is being addressed?
What issue is being addressed?
Rules
1. cc_archive
2. cc_bin
3. cc_hdrs
4. cc_so
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:

remove 'cc_library' out of the equation (no more targets that produce either archive or sol)
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

rules_cc_hdrs_map

Shortest possible example

Table of contents

What issue is being addressed?

How the issue is being addressed?

cc_archive

cc_bin

cc_hdrs

cc_so

HdrsMapInfo

actions.compile_kwargs

actions.link_to_archive_kwargs

actions.link_to_binary_kwargs

actions.link_to_so_kwargs

actions.prepare_for_compilation

providers_helper.materialize_hdrs_mapping

providers_helper.merge_cc_shared_library_infos

providers_helper.merge_hdrs_map_infos

providers_helper.new_hdrs_map

providers_helper.quotient_map_cc_shared_library_infos

providers_helper.quotient_map_hdrs_map_infos