Skip to content

Latest commit

 

History

History
166 lines (126 loc) · 4.5 KB

README.md

File metadata and controls

166 lines (126 loc) · 4.5 KB
Raw

rules_ll

OpenSSF Best Practices OpenSSF Scorecard

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.

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

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

🔗 Links

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