rules_ll

An upstream Clang/LLVM-based toolchain for contemporary C++ and heterogeneous programming.

This project interleaves Nix and Bazel with opinionated Starlark rules for C++.

Builds running within rules_ll-compatible workspaces achieve virtually perfect cache hit rates across machines, using C++ toolchains often several major versions ahead of most other remote execution setups.

The ll_* rules use a toolchain purpose-built around Clang/LLVM. You can't combine ll_* and cc_* targets at the moment, but you can still build cc_* projects in rules_ll-workspaces to leverage the remote execution setup and share caches.

✨ Setup

1. Install nix with flakes.

2. Create a rules_ll compatible workspace. To keep the development shell in sync with the rules_ll Bazel module, pin the flake to a specific commit:

   git init
   nix flake init -t github:eomii/rules_ll/<commit>

   The default toolchains include C++ and HIP for AMDGPU. If you also want to target NVPTX devices (Nvidia GPUs), make sure to read the CUDA license and set comment.allowUnfree and config.cudaSupport in flake.nix.

[!WARNING] Don't use the tags or releases from the GitHub repository. They were used in old versions of rules_ll and probably in a broken state. Use a pinned commit instead.

3. Enter the rules_ll development shell:

   nix develop

[!TIP] Strongly consider setting up direnv so that you don't need to remember running nix develop to enter the flake and exit to exit it.

4. Consider setting up at least a local remote cache as described in the remote execution guide.

🔗 Links

• Docs
• Guides
• Examples
• Discussions

🚀 C++ modules

Use the interfaces and exposed_interfaces attributes to build C++ modules. C++ modules guide.

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

ll_library(
    name = "mymodule",
    srcs = ["mymodule_impl.cpp"],
    exposed_interfaces = {
        "mymodule_interface.cppm": "mymodule",
    },
    compile_flags = ["-std=c++20"],
)

ll_binary(
    name = "main",
    srcs = ["main.cpp"],
    deps = [":mymodule"],
)

🧹 Clang-tidy

Build compilation databases to use Clang-Tidy as part of your workflows and CI pipelines. Clang-Tidy guide.

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

filegroup(
    name = "clang_tidy_config",
    srcs = [".clang-tidy"],
)

ll_compilation_database(
   name = "compile_commands",
   targets = [
      ":my_very_tidy_target",
   ],
   config = ":clang_tidy_config",
)

😷 Sanitizers

Integrate sanitizers in your builds with the sanitize attribute. Sanitizers guide.

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

ll_binary(
    name = "sanitizer_example",
    srcs = ["totally_didnt_shoot_myself_in_the_foot.cpp"],
    sanitize = ["address"],
)

🧮 CUDA and HIP

Use CUDA and HIP without any manual setup. CUDA and HIP guide.

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

ll_binary(
    name = "cuda_example",
    srcs = ["look_mum_no_cuda_setup.cu"],
    compilation_mode = "cuda_nvptx",  # Or "hip_nvptx". Or "hip_amdgpu".
    compile_flags = [
        "--std=c++20",
        "--offload-arch=sm_70",  # Your GPU model.
    ],
)

📜 License

Licensed under the Apache 2.0 License with LLVM exceptions.

This repository uses overlays and automated setups for the CUDA toolkit and HIP. Using compilation_mode for heterogeneous toolchains implies acceptance of their licenses.