//ll:defs.bzl#

These are the rules that should be imported in BUILD.bazel files.

To load e.g. the ll_binary rule:

load("@rules_ll//ll:defs.bzl", "ll_binary")

ll_binary#

ll_binary(name, angled_includes, compilation_mode, compile_flags, data, defines, deps, hdrs,
          includes, interfaces, libraries, link_flags, llvm_project_deps, relative_angled_includes,
          relative_includes, sanitize, srcs, toolchain_configuration)

Creates an executable.

Example:

ll_binary(
    srcs = ["my_executable.cpp"],
)

ATTRIBUTES

Name

Description

Type

Mandatory

Default

name

A unique name for this target.

Name

required

angled_includes

Additional angled include paths for this target.

Per default all inclusions are quoted includes (via -iquote). Paths added here are available as angled includes (via -I).

Only used for this target.

List of strings

optional

[]

compilation_mode

Enables compilation of heterogeneous single source files.

WARNING: VERY EXPERIMENTAL.

Prefer using this attribute over adding SYCL/HIP/CUDA flags manually in the ”compile_flags” and ”link_flags”.

See <TODO: GUIDE> for a detailed explanation of how this flag changes the autogenerated command line arguments/compile passes.

”cpp” will treat compilable sources as regular C++.

”cuda_nvidia” will treat compilable sources as CUDA kernels.

”hip_nvidia” will treat compilable sources as HIP kernels.

”sycl_cpu” will enable highly experimental SYCL CPU support using hipSYCL. Do not use this. It is not fully implemented yet.

”bootstrap” is used for the internal dependencies of the ll_toolchain such as libcxxabi etc.

String

optional

“cpp”

compile_flags

Additional flags for the compiler.

A list of strings [“-O3”, “-std=c++20”] will be appended to the compile command line arguments as -O3 -std=c++20.

Flag pairs like -Xclang -somearg need to be split into separate flags [“-Xclang”, “-somearg”].

Only used for this target.

List of strings

optional

[]

data

Additional files made available to the sandboxed actions executed within this rule. These files are not appended to the default line arguments, but are part of the inputs to the actions and may be added to command line arguments manually via the includes, and compile_flags (for ll_binary also link_flags) attributes.

This attribute may be used to make intermediary outputs from non-ll targets (e.g. from
rules_cc or filegroup) available to the rule.

List of labels

optional

[]

defines

Additional defines for this target.

A list of strings [“MYDEFINE_1”, “MYDEFINE_2”] will add -DMYDEFINE_1 -DMYDEFINE_2 to the compile command line.

Only used for this target.

List of strings

optional

[]

deps

The dependencies for this target.

Every dependency needs to be an ll_library.

List of labels

optional

[]

hdrs

Header files for this target.

Headers in this attribute will not be exported, i.e. any generated include paths are only used for this target and the header files are not made available to downstream targets.

When including header files as #include “some/path/myheader.h” their include paths need to be specified in the includes attribute as well.

List of labels

optional

[]

includes

Additional quoted include paths for this target.

When including a header not via #include “header.h”, but via #include “subdir/header.h”, the include path needs to be added here in addition to making the header available in the hdrs attribute.

Only used for this target.

List of strings

optional

[]

interfaces

Module interfaces for this target.

Interfaces need to be declared like

python         interfaces = {             “<interface_file>”: “<module_name>”,         }         
The module name is distinct from the filename and the target’s name attribute. This makes module naming arbitrarily flexible, for instance:
python         ll_library(             name = “mymodule”,             srcs = [                 “A_B.cpp”  # Implementation for module A.B.             ],             interfaces = {                 “A.cppm”: “A”,  # Interface without separate implementation.                 “A_B.cppm”: “A.B”,  # Interface for module A.B.             }         )         
Internally, interfaces will be precompiled and then compiled to objects named <filename>.interface.o. This way object files for modules implemented via separate interfaces and implementations (such as A.cpp in srcs and A.cppm in interfaces) do not clash.

Dictionary: Label -> String

optional

{}

libraries

Additional libraries linked to the final executable.

Adds these libraries to the command line arguments for the linker.

List of labels

optional

[]

link_flags

Additional flags for the linker.

For ll_binary: This is the place for adding library search paths and external link targets.

Assuming you have a library /some/path/libmylib.a on your host system, you can make mylib.a available to the linker by passing [“-L/some/path”, “-lmylib”] to this attribute.

Prefer using the libraries attribute for library files already present within the bazel build graph.

List of strings

optional

[]

llvm_project_deps

cc_library deps from the LLVM project overlay.

Using this attribute causes compile actions to add -idirafter include paths to clang/include and llvm/include for Clang/LLVM internal and generated headers.

Dependencies declared in this attribute will be compiled for the target platform using the original rules_cc overlay targets.

This attribute hijacks cc_library. Use with caution.

List of labels

optional

[]

relative_angled_includes

Additional angled include paths, relative to the target workspace.

This attribute is useful if we require custom include prefix stripping, but have dynamic paths, such as ones generated by bzlmod. So instead of using angled_includes = [“external/mydep.someversion/include”] we can use relative_angled_includes = [“include”], and the path to the workspace will be added automatically.

Only used for this target.

List of strings

optional

[]

relative_includes

Additional quoted include paths, relative to the target workspace.

This attribute is useful if we require custom include prefix stripping, but have dynamic paths, such as ones generated by bzlmod. So instead of using includes = [“external/mydep.someversion/include”] we can use relative_includes = [“include”], and the path to the workspace will be added automatically.

Only used for this target.

List of strings

optional

[]

sanitize

Enable sanitizers for this target.

Some sanitizers come with heavy performance penalties. Many combinations of multiple enabled sanitizers are invalid. If possible, use only one at a time.

Since sanitizers find issues during runtime, error reports are nondeterministic and not reproducible at an address level. Run sanitized executables multiple times and build them with different optimization levels to maximize coverage.

”address”: Enable AddressSanitizer to detect memory errors. Typical slowdown introduced is 2x. Executables that invoke CUDA-based kernels, including those created via HIP and SYCL, need to be run with ASAN_OPTIONS=protect_shadow_gap=0. ”leak”: Enable LeakSanitizer to detect memory leaks. This is already integrated in AddressSanitizer. Enable LeakSanitizer if you want to use it in standalone mode. Almost no performance overhead until the end of the process where leaks are detected. ”memory”: Enable MemorySanitizer to detect uninitialized reads. Typical slowdown introduced is 3x. Add ”-fsanitize-memory-track-origins=2” to the compile_flags attribute to track the origins of uninitialized values. ”undefined_behavior”: Enable UndefinedBehaviorSanitizer to detect undefined behavior. Small performance overhead. ”thread”: Enable ThreadSanitizer to detect data races. Typical slowdown is 5x-15x. Typical memory overhead is 5x-10x.

List of strings

optional

[]

srcs

Compilable source files for this target.

Only compilable files and object files [“.ll”, “.o”, “.S”, “.c”, “.cl”, “.cpp”] are allowed here.

Headers should be placed in the hdrs attribute.

List of labels

optional

[]

toolchain_configuration

TODO

Label

optional

//ll:current_ll_toolchain_configuration

ll_compilation_database#

ll_compilation_database(name, config, exclude, target)

Executable target for building a compilation database and running clang-tidy on it.

For a full guide see Using rules_ll with clang-tidy.

An example project using this rule is available at rules_ll/examples.

ATTRIBUTES

Name

Description

Type

Mandatory

Default

name

A unique name for this target.

Name

required

config

The label of a .clang-tidy configuration file.

This file should be at the root of your project directory.

Label

required

exclude

Exclude all targets whose path includes one at least one of the provided strings.

List of strings

optional

[]

target

The label for which the compilation database should be built.

Label

required

ll_library#

ll_library(name, angled_includes, bitcode_libraries, bitcode_link_flags, compilation_mode,
           compile_flags, data, defines, deps, emit, hdrs, includes, interfaces, llvm_project_deps,
           relative_angled_includes, relative_includes, sanitize, shared_object_link_flags, srcs,
           toolchain_configuration, transitive_angled_includes, transitive_defines, transitive_hdrs,
           transitive_includes, transitive_interfaces, transitive_relative_angled_includes,
           transitive_relative_includes)

Creates a static archive.

Example:

ll_library(
    srcs = ["my_library.cpp"],
)

ATTRIBUTES

Name

Description

Type

Mandatory

Default

name

A unique name for this target.

Name

required

angled_includes

Additional angled include paths for this target.

Per default all inclusions are quoted includes (via -iquote). Paths added here are available as angled includes (via -I).

Only used for this target.

List of strings

optional

[]

bitcode_libraries

Additional bitcode libraries that should be linked to the output.

Only used if emit includes ”bitcode”.

List of labels

optional

[]

bitcode_link_flags

Additional flags for the bitcode linker when emitting bitcode.

Only Used if emit includes ”bitcode”.

List of strings

optional

[]

compilation_mode

Enables compilation of heterogeneous single source files.

WARNING: VERY EXPERIMENTAL.

Prefer using this attribute over adding SYCL/HIP/CUDA flags manually in the ”compile_flags” and ”link_flags”.

See <TODO: GUIDE> for a detailed explanation of how this flag changes the autogenerated command line arguments/compile passes.

”cpp” will treat compilable sources as regular C++.

”cuda_nvidia” will treat compilable sources as CUDA kernels.

”hip_nvidia” will treat compilable sources as HIP kernels.

”sycl_cpu” will enable highly experimental SYCL CPU support using hipSYCL. Do not use this. It is not fully implemented yet.

”bootstrap” is used for the internal dependencies of the ll_toolchain such as libcxxabi etc.

String

optional

“cpp”

compile_flags

Additional flags for the compiler.

A list of strings [“-O3”, “-std=c++20”] will be appended to the compile command line arguments as -O3 -std=c++20.

Flag pairs like -Xclang -somearg need to be split into separate flags [“-Xclang”, “-somearg”].

Only used for this target.

List of strings

optional

[]

data

Additional files made available to the sandboxed actions executed within this rule. These files are not appended to the default line arguments, but are part of the inputs to the actions and may be added to command line arguments manually via the includes, and compile_flags (for ll_binary also link_flags) attributes.

This attribute may be used to make intermediary outputs from non-ll targets (e.g. from
rules_cc or filegroup) available to the rule.

List of labels

optional

[]

defines

Additional defines for this target.

A list of strings [“MYDEFINE_1”, “MYDEFINE_2”] will add -DMYDEFINE_1 -DMYDEFINE_2 to the compile command line.

Only used for this target.

List of strings

optional

[]

deps

The dependencies for this target.

Every dependency needs to be an ll_library.

List of labels

optional

[]

emit

Sets the output mode. Multiple values may be specified.

”archive” invokes the archiver and adds an archive with a .a extension to the outputs. ”shared_object” invokes the linker and adds a shared object with a .so extension to the outputs. ”bitcode” invokes the bitcode linker and adds an LLVM bitcode file with a .bc extension to the outputs. ”objects” adds loose object files to the outputs.

List of strings

optional

[“archive”]

hdrs

Header files for this target.

Headers in this attribute will not be exported, i.e. any generated include paths are only used for this target and the header files are not made available to downstream targets.

When including header files as #include “some/path/myheader.h” their include paths need to be specified in the includes attribute as well.

List of labels

optional

[]

includes

Additional quoted include paths for this target.

When including a header not via #include “header.h”, but via #include “subdir/header.h”, the include path needs to be added here in addition to making the header available in the hdrs attribute.

Only used for this target.

List of strings

optional

[]

interfaces

Module interfaces for this target.

Interfaces need to be declared like

python         interfaces = {             “<interface_file>”: “<module_name>”,         }         
The module name is distinct from the filename and the target’s name attribute. This makes module naming arbitrarily flexible, for instance:
python         ll_library(             name = “mymodule”,             srcs = [                 “A_B.cpp”  # Implementation for module A.B.             ],             interfaces = {                 “A.cppm”: “A”,  # Interface without separate implementation.                 “A_B.cppm”: “A.B”,  # Interface for module A.B.             }         )         
Internally, interfaces will be precompiled and then compiled to objects named <filename>.interface.o. This way object files for modules implemented via separate interfaces and implementations (such as A.cpp in srcs and A.cppm in interfaces) do not clash.

Dictionary: Label -> String

optional

{}

llvm_project_deps

cc_library deps from the LLVM project overlay.

Using this attribute causes compile actions to add -idirafter include paths to clang/include and llvm/include for Clang/LLVM internal and generated headers.

Dependencies declared in this attribute will be compiled for the target platform using the original rules_cc overlay targets.

This attribute hijacks cc_library. Use with caution.

List of labels

optional

[]

relative_angled_includes

Additional angled include paths, relative to the target workspace.

This attribute is useful if we require custom include prefix stripping, but have dynamic paths, such as ones generated by bzlmod. So instead of using angled_includes = [“external/mydep.someversion/include”] we can use relative_angled_includes = [“include”], and the path to the workspace will be added automatically.

Only used for this target.

List of strings

optional

[]

relative_includes

Additional quoted include paths, relative to the target workspace.

This attribute is useful if we require custom include prefix stripping, but have dynamic paths, such as ones generated by bzlmod. So instead of using includes = [“external/mydep.someversion/include”] we can use relative_includes = [“include”], and the path to the workspace will be added automatically.

Only used for this target.

List of strings

optional

[]

sanitize

Enable sanitizers for this target.

Some sanitizers come with heavy performance penalties. Many combinations of multiple enabled sanitizers are invalid. If possible, use only one at a time.

Since sanitizers find issues during runtime, error reports are nondeterministic and not reproducible at an address level. Run sanitized executables multiple times and build them with different optimization levels to maximize coverage.

”address”: Enable AddressSanitizer to detect memory errors. Typical slowdown introduced is 2x. Executables that invoke CUDA-based kernels, including those created via HIP and SYCL, need to be run with ASAN_OPTIONS=protect_shadow_gap=0. ”leak”: Enable LeakSanitizer to detect memory leaks. This is already integrated in AddressSanitizer. Enable LeakSanitizer if you want to use it in standalone mode. Almost no performance overhead until the end of the process where leaks are detected. ”memory”: Enable MemorySanitizer to detect uninitialized reads. Typical slowdown introduced is 3x. Add ”-fsanitize-memory-track-origins=2” to the compile_flags attribute to track the origins of uninitialized values. ”undefined_behavior”: Enable UndefinedBehaviorSanitizer to detect undefined behavior. Small performance overhead. ”thread”: Enable ThreadSanitizer to detect data races. Typical slowdown is 5x-15x. Typical memory overhead is 5x-10x.

List of strings

optional

[]

shared_object_link_flags

Additional flags for the linker when emitting shared objects.

Only used if emit includes ”shared_object”.

List of strings

optional

[]

srcs

Compilable source files for this target.

Only compilable files and object files [“.ll”, “.o”, “.S”, “.c”, “.cl”, “.cpp”] are allowed here.

Headers should be placed in the hdrs attribute.

List of labels

optional

[]

toolchain_configuration

TODO

Label

optional

//ll:current_ll_toolchain_configuration

transitive_angled_includes

Additional transitive angled include paths for this target.

Includes in this attribute will be added to the compile command line arguments for all downstream targets.

List of strings

optional

[]

transitive_defines

Additional transitive defines for this target.

These defines will be defined by all depending downstream targets.

List of strings

optional

[]

transitive_hdrs

Transitive headers for this target.

Any transitive headers will be exported (copied) to the build directory.

Transitive headers are available to depending downstream targets.

List of labels

optional

[]

transitive_includes

Additional transitive include paths for this target.

Includes in this attribute will be added to the compile command line arguments for all downstream targets.

List of strings

optional

[]

transitive_interfaces

Transitive interfaces for this target.

Like interfaces, but both the precompiled modules and the compiled objects derived from files in this attribute are transitive.

Dictionary: Label -> String

optional

{}

transitive_relative_angled_includes

Additional transitive angled include paths, relative to the original target workspace.

Includes in this attribute will be added to the compile command line arguments for all downstream targets.

List of strings

optional

[]

transitive_relative_includes

Additional transitive include paths, relative to the original target workspace.

Includes in this attribute will be added to the compile command line arguments for all downstream targets.

List of strings

optional

[]