README.md
1# C++ rules for Bazel
2
3* Postsubmit [](https://buildkite.com/bazel/rules-cc)
4* Postsubmit + Current Bazel Incompatible flags [](https://buildkite.com/bazel/rules-cc-plus-bazelisk-migrate)
5
6This repository contains a Starlark implementation of C++ rules in Bazel.
7
8The rules are being incrementally converted from their native implementations in the [Bazel source tree](https://source.bazel.build/bazel/+/master:src/main/java/com/google/devtools/build/lib/rules/cpp/).
9
10For the list of C++ rules, see the Bazel
11[documentation](https://docs.bazel.build/versions/main/be/overview.html).
12
13# Getting Started
14
15There is no need to use rules from this repository just yet. If you want to use
16`rules_cc` anyway, add the following to your `WORKSPACE` file:
17
18```starlark
19load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
20
21http_archive(
22 name = "rules_cc",
23 urls = ["https://github.com/bazelbuild/rules_cc/archive/refs/tags/<VERSION>.tar.gz"],
24 sha256 = "...",
25)
26```
27
28Then, in your `BUILD` files, import and use the rules:
29
30```starlark
31load("@rules_cc//cc:defs.bzl", "cc_library")
32
33cc_library(
34 ...
35)
36```
37
38# Using the rules_cc toolchain
39
40This repo contains an auto-detecting toolchain that expects to find tools installed on your host machine.
41This is non-hermetic, and may have varying behaviors depending on the versions of tools found.
42
43There are third-party contributed hermetic toolchains you may want to investigate:
44
45- LLVM: <https://github.com/grailbio/bazel-toolchain>
46- GCC (Linux only): <https://github.com/aspect-build/gcc-toolchain>
47- zig cc: <https://github.com/uber/hermetic_cc_toolchain>
48
49If you'd like to use the cc toolchain defined in this repo, add this to
50your WORKSPACE after you include rules_cc:
51
52```bzl
53load("@rules_cc//cc:repositories.bzl", "rules_cc_dependencies", "rules_cc_toolchains")
54
55rules_cc_dependencies()
56
57rules_cc_toolchains()
58```
59
60# Migration Tools
61
62This repository also contains migration tools that can be used to migrate your
63project for Bazel incompatible changes.
64
65## Legacy fields migrator
66
67Script that migrates legacy crosstool fields into features
68([incompatible flag](https://github.com/bazelbuild/bazel/issues/6861),
69[tracking issue](https://github.com/bazelbuild/bazel/issues/5883)).
70
71TLDR:
72
73```
74bazel run @rules_cc//tools/migration:legacy_fields_migrator -- \
75 --input=my_toolchain/CROSSTOOL \
76 --inline
77```
78
79# Contributing
80
81Bazel and `rules_cc` are the work of many contributors. We appreciate your help!
82
83To contribute, please read the contribution guidelines: [CONTRIBUTING.md](https://github.com/bazelbuild/rules_cc/blob/main/CONTRIBUTING.md).
84
85Note that the `rules_cc` use the GitHub issue tracker for bug reports and feature requests only.
86For asking questions see:
87
88* [Stack Overflow](https://stackoverflow.com/questions/tagged/bazel)
89* [`rules_cc` mailing list](https://groups.google.com/forum/#!forum/cc-bazel-discuss)
90* Slack channel `#cc` on [slack.bazel.build](https://slack.bazel.build)
91
){kind=link}
){kind=link}