Skip to content

//ll:defs.bzl

Import these rules in your BUILD.bazel files.

To load for example the ll_binary rule:

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

ll_binary

ll_binary(name, deps, srcs, data, hdrs, angled_includes, compilation_mode, compile_flags, defines,
          depends_on_llvm, exposed_angled_includes, exposed_defines, exposed_hdrs, exposed_includes,
          exposed_interfaces, includes, interfaces, libraries, link_flags, sanitize,
          toolchain_configuration)

Creates an executable.

Example:

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

Name Description
name Name, required.

A unique name for this target.
deps List of labels, optional, defaults to [].

The dependencies for this target.

Use ll_library targets here. Other targets won't work.
srcs List of labels, optional, defaults to [].

Compilable source files for this target.

Allowed file extensions: [".ll", ".o", ".S", ".c", ".cl", ".cpp"].

Place headers in the hdrs attribute.
data List of labels, optional, defaults to [].

Extra files made available to compilation and linking steps.

Not appended to the default command line arguments, but available to actions. Reference these files manually for instance in the includes, and compile_flags attributes.

Use this attribute to make intermediary outputs from non-ll targets, for example from rules_cc or filegroup, available to the rule.
hdrs List of labels, optional, defaults to [].

Header files for this target.

When including a header file with a nested path, for instance #include "some/path/myheader.h", add "some/path" to includes to make it visible to the rule.

Unavailable to downstream targets.
angled_includes List of strings, optional, defaults to [].

Angled include paths, relative to the target workspace.

Useful if you require include prefix stripping for dynamic paths, for instance the ones generated by bzlmod. Instead of compile_flags = ["-Iexternal/mydep.someversion/include"], use angled_includes = ["include"] to add the path to the workspace automatically.

Expands paths starting with $(GENERATED) to the workspace location in the GENDIR path.

Unavailable to downstream targets.
compilation_mode String, optional, defaults to "cpp".

Enables compilation of heterogeneous single source files.

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

See CUDA and HIP.

"cpp" The default C++ toolchain.

"cuda_nvptx" The CUDA toolchain.

"hip_nvptx" The HIP toolchain.

"omp_cpu" The OpenMP CPU toolchain.

"bootstrap" The bootstrap toolchain used by internal dependencies of the ll_toolchain.
compile_flags List of strings, optional, defaults to [].

Flags for the compiler.

Pass a list of strings here. For instance ["-O3", "-std=c++20"].

Split flag pairs -Xclang -somearg into separate flags ["-Xclang", "-somearg"].

Unavailable to downstream targets.
defines List of strings, optional, defaults to [].

Defines for this target.

Pass a list of strings here. For instance ["MYDEFINE_1", "MYDEFINE_2"].

Unavailable to downstream targets.
depends_on_llvm Boolean, optional, defaults to False.

Whether this target directly depends on targets from the llvm-project-overlay.

Setting this to True makes the cc_library targets from the LLVM project overlay available to this target.
exposed_angled_includes List of strings, optional, defaults to [].

Exposed angled include paths, relative to the original target workspace.

Expands paths starting with $(GENERATED) to the workspace location in the GENDIR path.

Added to the compile command line arguments of direct dependents.
exposed_defines List of strings, optional, defaults to [].

Exposed defines for this target.

Added to the compile command line arguments of direct dependents.
exposed_hdrs List of labels, optional, defaults to [].

Exposed headers for this target.

Direct dependents can see exposed headers. Put the public API headers for libraries here.
exposed_includes List of strings, optional, defaults to [].

Exposed include paths, relative to the original target workspace.

Expands paths starting with $(GENERATED) to the workspace location in the GENDIR path.

Added to the compile command line arguments of direct dependents.
exposed_interfaces Dictionary: Label -> String, optional, defaults to {}.

Transitive interfaces for this target.

See C++ modules for a guide.

Makes precompiled modules and compiled objects visible to direct dependents. Files in this attribute can see BMIs from modules in interfaces.

Primary module interfaces go here.
includes List of strings, optional, defaults to [].

Include paths, relative to the target workspace.

Uses -iquote.

Useful if you need custom include prefix stripping for dynamic paths, for instance the ones generated by bzlmod. Instead of compile_flags = ["-iquoteexternal/mydep.someversion/include"], use includes = ["include"] to add the path to the workspace automatically.

Expands paths starting with $(GENERATED) to the workspace location in the GENDIR path.

Unavailable to downstream targets.
interfaces Dictionary: Label -> String, optional, defaults to {}.

Module interfaces for this target.

See C++ modules for a guide.

Makes precompiled modules and compiled objects visible to direct dependents and to exposed_interfaces.

For instance, you can put module partitions in interfaces and the primary module interface in exposed_interfaces.

Files in the same interfaces attribute can't see each other's BMIs.
libraries List of labels, optional, defaults to [].

Libraries linked to the final executable.

Adds these libraries to the command line arguments for the linker.
link_flags List of strings, optional, defaults to [].

Flags for the linker.

Place library search paths and external link targets here.

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 the libraries attribute for library files already present within the Bazel build graph.
sanitize List of strings, optional, defaults to [].

Enable sanitizers for this target.

See the Sanitizers guide.

Some sanitizers come with heavy performance penalties. Enabling several sanitizers at the same time often breaks builds. If possible, use just one at a time.

Sanitizers produce nondeterministic error reports. Run sanitized executables several times and build them with different optimization levels to maximize coverage.

"address": Enable AddressSanitizer to detect memory errors.

"leak": Enable LeakSanitizer to detect memory leaks.

"memory": Enable MemorySanitizer to detect uninitialized reads.

"undefined_behavior": Enable UndefinedBehaviorSanitizer to detect undefined behavior.

"thread": Enable ThreadSanitizer to detect data races.
toolchain_configuration Label, optional, defaults to //ll:current_ll_toolchain_configuration.

TODO

ll_compilation_database

ll_compilation_database(name, config, exclude, targets)

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

For a full guide see Clang-Tidy.

See rules_ll/examples for examples. attributes

Name Description
name Name, required.

A unique name for this target.
config Label, required.

The label of a .clang-tidy configuration file.
exclude List of strings, optional, defaults to [].

Exclude all targets whose path includes one at least one of the provided strings.
targets List of labels, required.

The labels added to the compilation database.

ll_coverage_test

ll_coverage_test(name, target)

TODO attributes

Name Description
name Name, required.

A unique name for this target.
target Label, required.

The executable to run and collect coverage data from.

ll_library

ll_library(name, deps, srcs, data, hdrs, angled_includes, compilation_mode, compile_flags, defines,
           depends_on_llvm, emit, exposed_angled_includes, exposed_defines, exposed_hdrs,
           exposed_includes, exposed_interfaces, includes, interfaces, sanitize,
           shared_object_link_flags, toolchain_configuration)

Creates a static archive.

Example:

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

Name Description
name Name, required.

A unique name for this target.
deps List of labels, optional, defaults to [].

The dependencies for this target.

Use ll_library targets here. Other targets won't work.
srcs List of labels, optional, defaults to [].

Compilable source files for this target.

Allowed file extensions: [".ll", ".o", ".S", ".c", ".cl", ".cpp"].

Place headers in the hdrs attribute.
data List of labels, optional, defaults to [].

Extra files made available to compilation and linking steps.

Not appended to the default command line arguments, but available to actions. Reference these files manually for instance in the includes, and compile_flags attributes.

Use this attribute to make intermediary outputs from non-ll targets, for example from rules_cc or filegroup, available to the rule.
hdrs List of labels, optional, defaults to [].

Header files for this target.

When including a header file with a nested path, for instance #include "some/path/myheader.h", add "some/path" to includes to make it visible to the rule.

Unavailable to downstream targets.
angled_includes List of strings, optional, defaults to [].

Angled include paths, relative to the target workspace.

Useful if you require include prefix stripping for dynamic paths, for instance the ones generated by bzlmod. Instead of compile_flags = ["-Iexternal/mydep.someversion/include"], use angled_includes = ["include"] to add the path to the workspace automatically.

Expands paths starting with $(GENERATED) to the workspace location in the GENDIR path.

Unavailable to downstream targets.
compilation_mode String, optional, defaults to "cpp".

Enables compilation of heterogeneous single source files.

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

See CUDA and HIP.

"cpp" The default C++ toolchain.

"cuda_nvptx" The CUDA toolchain.

"hip_nvptx" The HIP toolchain.

"omp_cpu" The OpenMP CPU toolchain.

"bootstrap" The bootstrap toolchain used by internal dependencies of the ll_toolchain.
compile_flags List of strings, optional, defaults to [].

Flags for the compiler.

Pass a list of strings here. For instance ["-O3", "-std=c++20"].

Split flag pairs -Xclang -somearg into separate flags ["-Xclang", "-somearg"].

Unavailable to downstream targets.
defines List of strings, optional, defaults to [].

Defines for this target.

Pass a list of strings here. For instance ["MYDEFINE_1", "MYDEFINE_2"].

Unavailable to downstream targets.
depends_on_llvm Boolean, optional, defaults to False.

Whether this target directly depends on targets from the llvm-project-overlay.

Setting this to True makes the cc_library targets from the LLVM project overlay available to this target.
emit List of strings, optional, defaults to ["archive"].

Sets the output mode.

You can enable several output types at the same time.

"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.

"objects" adds loose object files to the outputs.
exposed_angled_includes List of strings, optional, defaults to [].

Exposed angled include paths, relative to the original target workspace.

Expands paths starting with $(GENERATED) to the workspace location in the GENDIR path.

Added to the compile command line arguments of direct dependents.
exposed_defines List of strings, optional, defaults to [].

Exposed defines for this target.

Added to the compile command line arguments of direct dependents.
exposed_hdrs List of labels, optional, defaults to [].

Exposed headers for this target.

Direct dependents can see exposed headers. Put the public API headers for libraries here.
exposed_includes List of strings, optional, defaults to [].

Exposed include paths, relative to the original target workspace.

Expands paths starting with $(GENERATED) to the workspace location in the GENDIR path.

Added to the compile command line arguments of direct dependents.
exposed_interfaces Dictionary: Label -> String, optional, defaults to {}.

Transitive interfaces for this target.

See C++ modules for a guide.

Makes precompiled modules and compiled objects visible to direct dependents. Files in this attribute can see BMIs from modules in interfaces.

Primary module interfaces go here.
includes List of strings, optional, defaults to [].

Include paths, relative to the target workspace.

Uses -iquote.

Useful if you need custom include prefix stripping for dynamic paths, for instance the ones generated by bzlmod. Instead of compile_flags = ["-iquoteexternal/mydep.someversion/include"], use includes = ["include"] to add the path to the workspace automatically.

Expands paths starting with $(GENERATED) to the workspace location in the GENDIR path.

Unavailable to downstream targets.
interfaces Dictionary: Label -> String, optional, defaults to {}.

Module interfaces for this target.

See C++ modules for a guide.

Makes precompiled modules and compiled objects visible to direct dependents and to exposed_interfaces.

For instance, you can put module partitions in interfaces and the primary module interface in exposed_interfaces.

Files in the same interfaces attribute can't see each other's BMIs.
sanitize List of strings, optional, defaults to [].

Enable sanitizers for this target.

See the Sanitizers guide.

Some sanitizers come with heavy performance penalties. Enabling several sanitizers at the same time often breaks builds. If possible, use just one at a time.

Sanitizers produce nondeterministic error reports. Run sanitized executables several times and build them with different optimization levels to maximize coverage.

"address": Enable AddressSanitizer to detect memory errors.

"leak": Enable LeakSanitizer to detect memory leaks.

"memory": Enable MemorySanitizer to detect uninitialized reads.

"undefined_behavior": Enable UndefinedBehaviorSanitizer to detect undefined behavior.

"thread": Enable ThreadSanitizer to detect data races.
shared_object_link_flags List of strings, optional, defaults to [].

Flags for the linker when emitting shared objects.

Used if emit includes "shared_object".
toolchain_configuration Label, optional, defaults to //ll:current_ll_toolchain_configuration.

TODO

ll_test

ll_test(name, deps, srcs, data, hdrs, angled_includes, compilation_mode, compile_flags, defines,
        depends_on_llvm, exposed_angled_includes, exposed_defines, exposed_hdrs, exposed_includes,
        exposed_interfaces, includes, interfaces, libraries, link_flags, sanitize,
        toolchain_configuration)

Testable wrapper around ll_binary.

Consider using this rule over skylib's native_test targets to propagate shared libraries to the test invocations.

Example:

ll_test(
    name = "amdgpu_test",
    srcs = ["my_executable.cpp"],
    compilation_mode = "hip_amdgpu",
    compile_flags = OFFLOAD_ALL_AMDGPU + [
        "-std=c++20",
    ],
    tags = ["amdgpu"],  # Not required, but makes grouping tests easier.
)
attributes

Name Description
name Name, required.

A unique name for this target.
deps List of labels, optional, defaults to [].

The dependencies for this target.

Use ll_library targets here. Other targets won't work.
srcs List of labels, optional, defaults to [].

Compilable source files for this target.

Allowed file extensions: [".ll", ".o", ".S", ".c", ".cl", ".cpp"].

Place headers in the hdrs attribute.
data List of labels, optional, defaults to [].

Extra files made available to compilation and linking steps.

Not appended to the default command line arguments, but available to actions. Reference these files manually for instance in the includes, and compile_flags attributes.

Use this attribute to make intermediary outputs from non-ll targets, for example from rules_cc or filegroup, available to the rule.
hdrs List of labels, optional, defaults to [].

Header files for this target.

When including a header file with a nested path, for instance #include "some/path/myheader.h", add "some/path" to includes to make it visible to the rule.

Unavailable to downstream targets.
angled_includes List of strings, optional, defaults to [].

Angled include paths, relative to the target workspace.

Useful if you require include prefix stripping for dynamic paths, for instance the ones generated by bzlmod. Instead of compile_flags = ["-Iexternal/mydep.someversion/include"], use angled_includes = ["include"] to add the path to the workspace automatically.

Expands paths starting with $(GENERATED) to the workspace location in the GENDIR path.

Unavailable to downstream targets.
compilation_mode String, optional, defaults to "cpp".

Enables compilation of heterogeneous single source files.

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

See CUDA and HIP.

"cpp" The default C++ toolchain.

"cuda_nvptx" The CUDA toolchain.

"hip_nvptx" The HIP toolchain.

"omp_cpu" The OpenMP CPU toolchain.

"bootstrap" The bootstrap toolchain used by internal dependencies of the ll_toolchain.
compile_flags List of strings, optional, defaults to [].

Flags for the compiler.

Pass a list of strings here. For instance ["-O3", "-std=c++20"].

Split flag pairs -Xclang -somearg into separate flags ["-Xclang", "-somearg"].

Unavailable to downstream targets.
defines List of strings, optional, defaults to [].

Defines for this target.

Pass a list of strings here. For instance ["MYDEFINE_1", "MYDEFINE_2"].

Unavailable to downstream targets.
depends_on_llvm Boolean, optional, defaults to False.

Whether this target directly depends on targets from the llvm-project-overlay.

Setting this to True makes the cc_library targets from the LLVM project overlay available to this target.
exposed_angled_includes List of strings, optional, defaults to [].

Exposed angled include paths, relative to the original target workspace.

Expands paths starting with $(GENERATED) to the workspace location in the GENDIR path.

Added to the compile command line arguments of direct dependents.
exposed_defines List of strings, optional, defaults to [].

Exposed defines for this target.

Added to the compile command line arguments of direct dependents.
exposed_hdrs List of labels, optional, defaults to [].

Exposed headers for this target.

Direct dependents can see exposed headers. Put the public API headers for libraries here.
exposed_includes List of strings, optional, defaults to [].

Exposed include paths, relative to the original target workspace.

Expands paths starting with $(GENERATED) to the workspace location in the GENDIR path.

Added to the compile command line arguments of direct dependents.
exposed_interfaces Dictionary: Label -> String, optional, defaults to {}.

Transitive interfaces for this target.

See C++ modules for a guide.

Makes precompiled modules and compiled objects visible to direct dependents. Files in this attribute can see BMIs from modules in interfaces.

Primary module interfaces go here.
includes List of strings, optional, defaults to [].

Include paths, relative to the target workspace.

Uses -iquote.

Useful if you need custom include prefix stripping for dynamic paths, for instance the ones generated by bzlmod. Instead of compile_flags = ["-iquoteexternal/mydep.someversion/include"], use includes = ["include"] to add the path to the workspace automatically.

Expands paths starting with $(GENERATED) to the workspace location in the GENDIR path.

Unavailable to downstream targets.
interfaces Dictionary: Label -> String, optional, defaults to {}.

Module interfaces for this target.

See C++ modules for a guide.

Makes precompiled modules and compiled objects visible to direct dependents and to exposed_interfaces.

For instance, you can put module partitions in interfaces and the primary module interface in exposed_interfaces.

Files in the same interfaces attribute can't see each other's BMIs.
libraries List of labels, optional, defaults to [].

Libraries linked to the final executable.

Adds these libraries to the command line arguments for the linker.
link_flags List of strings, optional, defaults to [].

Flags for the linker.

Place library search paths and external link targets here.

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 the libraries attribute for library files already present within the Bazel build graph.
sanitize List of strings, optional, defaults to [].

Enable sanitizers for this target.

See the Sanitizers guide.

Some sanitizers come with heavy performance penalties. Enabling several sanitizers at the same time often breaks builds. If possible, use just one at a time.

Sanitizers produce nondeterministic error reports. Run sanitized executables several times and build them with different optimization levels to maximize coverage.

"address": Enable AddressSanitizer to detect memory errors.

"leak": Enable LeakSanitizer to detect memory leaks.

"memory": Enable MemorySanitizer to detect uninitialized reads.

"undefined_behavior": Enable UndefinedBehaviorSanitizer to detect undefined behavior.

"thread": Enable ThreadSanitizer to detect data races.
toolchain_configuration Label, optional, defaults to //ll:current_ll_toolchain_configuration.

TODO