aboutsummaryrefslogtreecommitdiff
path: root/pw_toolchain_bazel/docs.rst
blob: 075dc3f7bec1f95b4dbb6dbd486095efb0b085aa (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
.. _module-pw_toolchain_bazel:

==================
pw_toolchain_bazel
==================

.. pigweed-module::
   :name: pw_toolchain_bazel
   :tagline: Modular Bazel C/C++ toolchain API
   :status: unstable
   :languages: Starlark

Assembling a complete, hermetic toolchain with Bazel using the native primitives
can be quite challenging. Additionally, Bazel's native API for declaring C/C++
toolchains doesn't inherently encourage modularity or reusability.

``pw_toolchain_bazel`` provides a suite of building blocks that make the process
of assembling a complete, hermetic toolchain significantly easier. The Bazel
rules introduced by this module push the vast majority of a toolchain's
declaration into build files, and encourages reusability through sharing of
flag groups, tools, and toolchain feature implementations.

While this module does **not** provide a hermetic toolchain, Pigweed provides
`fully instantiated and supported toolchains <https://cs.opensource.google/pigweed/pigweed/+/main:pw_toolchain/host_clang/BUILD.bazel>`_
that are a useful reference for building your own toolchain.

.. warning::
   `b/309533028 <https://issues.pigweed.dev/309533028>`_\: This module is under
   construction and is subject to major breaking changes.

.. grid:: 1

   .. grid-item-card:: :octicon:`info` API reference
      :link: module-pw_toolchain_bazel-api
      :link-type: ref
      :class-item: sales-pitch-cta-primary

      Detailed reference information about the pw_toolchain_bazel API.

.. grid:: 1

   .. grid-item-card:: :octicon:`file` Original SEED
      :link: seed-0113
      :link-type: ref
      :class-item: sales-pitch-cta-secondary

      SEED-0113: Add modular Bazel C/C++ toolchain API

------------
Dependencies
------------
This module is not permitted to have dependencies on other modules. When this
module stabilizes, it will be broken out into a separate repository.

.. toctree::
   :hidden:
   :maxdepth: 1

   API reference <api>