diff options
Diffstat (limited to 'pw_toolchain_bazel/api.rst')
| -rw-r--r-- | pw_toolchain_bazel/api.rst | 298 |
1 files changed, 298 insertions, 0 deletions
diff --git a/pw_toolchain_bazel/api.rst b/pw_toolchain_bazel/api.rst new file mode 100644 index 000000000..e0e61d33f --- /dev/null +++ b/pw_toolchain_bazel/api.rst @@ -0,0 +1,298 @@ +.. _module-pw_toolchain_bazel-api: + +============= +API reference +============= + +.. py:class:: pw_cc_toolchain + + This rule is the core of a C/C++ toolchain definition. Critically, it is + intended to fully specify the following: + + * Which tools to use for various compile/link actions. + * Which `well-known features <https://bazel.build/docs/cc-toolchain-config-reference#wellknown-features>`_ + are supported. + * Which flags to apply to various actions. + + .. py:attribute:: feature_deps + :type: List[label] + + ``pw_cc_toolchain_feature`` labels that provide features for this toolchain. + + .. py:attribute:: ar + :type: File + + Path to the tool to use for ``ar`` (static link) actions. + + .. py:attribute:: cpp + :type: File + + Path to the tool to use for C++ compile actions. + + .. py:attribute:: gcc + :type: File + + Path to the tool to use for C compile actions. + + .. py:attribute:: gcov + :type: File + + Path to the tool to use for generating code coverage data. + + .. py:attribute:: ld + :type: File + + Path to the tool to use for link actions. + + .. py:attribute:: strip + :type: File + + Path to the tool to use for strip actions. + + .. py:attribute:: objcopy + :type: File + + Path to the tool to use for objcopy actions. + + .. py:attribute:: objdump + :type: File + + Path to the tool to use for objdump actions. + + .. py:attribute:: action_config_flag_sets + :type: List[label] + + List of flag sets to apply to the respective ``action_config``\s. The vast + majority of labels listed here will point to :py:class:`pw_cc_flag_set` + rules. + + .. py:attribute:: toolchain_identifier + :type: str + + See `cc_common.create_cc_toolchain_config_info() <https://bazel.build/rules/lib/toplevel/cc_common#create_cc_toolchain_config_info>`_\. + + .. py:attribute:: host_system_name + :type: str + + See `cc_common.create_cc_toolchain_config_info() <https://bazel.build/rules/lib/toplevel/cc_common#create_cc_toolchain_config_info>`_\. + + .. py:attribute:: target_system_name + :type: str + + See `cc_common.create_cc_toolchain_config_info() <https://bazel.build/rules/lib/toplevel/cc_common#create_cc_toolchain_config_info>`_\. + + .. py:attribute:: target_cpu + :type: str + + See `cc_common.create_cc_toolchain_config_info() <https://bazel.build/rules/lib/toplevel/cc_common#create_cc_toolchain_config_info>`_\. + + .. py:attribute:: target_libc + :type: str + + See `cc_common.create_cc_toolchain_config_info() <https://bazel.build/rules/lib/toplevel/cc_common#create_cc_toolchain_config_info>`_\. + + .. py:attribute:: compiler + :type: str + + See `cc_common.create_cc_toolchain_config_info() <https://bazel.build/rules/lib/toplevel/cc_common#create_cc_toolchain_config_info>`_\. + + .. py:attribute:: abi_version + :type: str + + See `cc_common.create_cc_toolchain_config_info() <https://bazel.build/rules/lib/toplevel/cc_common#create_cc_toolchain_config_info>`_\. + + .. py:attribute:: abi_libc_version + :type: str + + See `cc_common.create_cc_toolchain_config_info() <https://bazel.build/rules/lib/toplevel/cc_common#create_cc_toolchain_config_info>`_\. + + .. py:attribute:: cc_target_os + :type: str + + See `cc_common.create_cc_toolchain_config_info() <https://bazel.build/rules/lib/toplevel/cc_common#create_cc_toolchain_config_info>`_\. + +.. py:class:: pw_cc_flag_set + + Declares an ordered set of flags bound to a set of actions. + + Flag sets can be attached to a :py:class:`pw_cc_toolchain` via + :py:attr:`pw_cc_toolchain.action_config_flag_sets`\. + + Examples: + + .. code-block:: py + + pw_cc_flag_set( + name = "warnings_as_errors", + flags = ["-Werror"], + ) + + pw_cc_flag_set( + name = "layering_check", + flag_groups = [ + ":strict_module_headers", + ":dependent_module_map_files", + ], + ) + + .. inclusive-language: disable + + Note: In the vast majority of cases, alphabetical sorting is not desirable + for the :py:attr:`pw_cc_flag_set.flags` and + :py:attr:`pw_cc_flag_set.flag_groups` attributes. + `Buildifier <https://github.com/bazelbuild/buildtools/blob/master/buildifier/README.md>`_ + shouldn't ever try to sort these, but in the off chance it starts to these + members should be listed as exceptions in the ``SortableDenylist``. + + .. inclusive-language: enable + + .. py:attribute:: actions + :type: List[str] + + A list of action names that this flag set applies to. + + .. inclusive-language: disable + + Valid choices are listed at + `@rules_cc//cc:action_names.bzl <https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/action_names.bzl>`_\. + + .. inclusive-language: enable + + It is possible for some needed action names to not be enumerated in this list, + so there is not rigid validation for these strings. Prefer using constants + rather than manually typing action names. + + .. py:attribute:: flags + :type: List[str] + + Flags that should be applied to the specified actions. + + These are evaluated in order, with earlier flags appearing earlier in the + invocation of the underlying tool. If you need expansion logic, prefer + enumerating flags in a :py:class:`pw_cc_flag_group` or create a custom + rule that provides ``FlagGroupInfo``. + + Note: :py:attr:`pw_cc_flag_set.flags` and + :py:attr:`pw_cc_flag_set.flag_groups` are mutually exclusive. + + .. py:attribute:: flag_groups + :type: List[label] + + Labels pointing to :py:class:`pw_cc_flag_group` rules. + + This is intended to be compatible with any other rules that provide + ``FlagGroupInfo``. These are evaluated in order, with earlier flag groups + appearing earlier in the invocation of the underlying tool. + + Note: :py:attr:`pw_cc_flag_set.flag_groups` and + :py:attr:`pw_cc_flag_set.flags` are mutually exclusive. + +.. py:class:: pw_cc_flag_group + + Declares an (optionally parametric) ordered set of flags. + + :py:class:`pw_cc_flag_group` rules are expected to be consumed exclusively by + :py:class:`pw_cc_flag_set` rules. Though simple lists of flags can be + expressed by populating ``flags`` on a :py:class:`pw_cc_flag_set`, + :py:class:`pw_cc_flag_group` provides additional power in the following two + ways: + + 1. Iteration and conditional expansion. Using + :py:attr:`pw_cc_flag_group.iterate_over`, + :py:attr:`pw_cc_flag_group.expand_if_available`\, and + :py:attr:`pw_cc_flag_group.expand_if_not_available`\, more complex + flag expressions can be made. This is critical for implementing things + like the ``libraries_to_link`` feature, where library names are + transformed into flags that end up in the final link invocation. + + Note: ``expand_if_equal``, ``expand_if_true``, and ``expand_if_false`` + are not yet supported. + + 2. Flags are tool-independent. A :py:class:`pw_cc_flag_group` expresses + ordered flags that may be reused across various + :py:class:`pw_cc_flag_set` rules. This is useful for cases where multiple + :py:class:`pw_cc_flag_set` rules must be created to implement a feature + for which flags are slightly different depending on the action (e.g. + compile vs link). Common flags can be expressed in a shared + :py:class:`pw_cc_flag_group`, and the differences can be relegated to + separate :py:class:`pw_cc_flag_group` instances. + + Examples: + + .. code-block:: py + + pw_cc_flag_group( + name = "user_compile_flag_expansion", + flags = ["%{user_compile_flags}"], + iterate_over = "user_compile_flags", + expand_if_available = "user_compile_flags", + ) + + # This flag_group might be referenced from various FDO-related + # `pw_cc_flag_set` rules. More importantly, the flag sets pulling this in + # may apply to different sets of actions. + pw_cc_flag_group( + name = "fdo_profile_correction", + flags = ["-fprofile-correction"], + expand_if_available = "fdo_profile_path", + ) + + .. py:attribute:: flags + :type: List[str] + + List of flags provided by this rule. + + For extremely complex expressions of flags that require nested flag groups + with multiple layers of expansion, prefer creating a custom rule in + `Starlark <https://bazel.build/rules/language>`_ that provides + ``FlagGroupInfo`` or ``FlagSetInfo``. + + + .. py:attribute:: iterate_over + :type: str + + Expands :py:attr:`pw_cc_flag_group.flags` for items in the named list. + + Toolchain actions have various variables accessible as names that can be + used to guide flag expansions. For variables that are lists, + :py:attr:`pw_cc_flag_group.iterate_over` must be used to expand the list into a series of flags. + + Note that :py:attr:`pw_cc_flag_group.iterate_over` is the string name of a + build variable, and not an actual list. Valid options are listed in the + `C++ Toolchain Configuration <https://bazel.build/docs/cc-toolchain-config-reference#cctoolchainconfiginfo-build-variables>`_ + reference. + + + + Note that the flag expansion stamps out the entire list of flags in + :py:attr:`pw_cc_flag_group.flags` once for each item in the list. + + Example: + + .. code-block:: py + + # Expands each path in ``system_include_paths`` to a series of + # ``-isystem`` includes. + # + # Example input: + # system_include_paths = ["/usr/local/include", "/usr/include"] + # + # Expected result: + # "-isystem /usr/local/include -isystem /usr/include" + pw_cc_flag_group( + name = "system_include_paths", + flags = ["-isystem", "%{system_include_paths}"], + iterate_over = "system_include_paths", + ) + + .. py:attribute:: expand_if_available + :type: str + + Expands the expression in :py:attr:`pw_cc_flag_group.flags` if the + specified build variable is set. + + .. py:attribute:: expand_if_not_available + :type: str + + Expands the expression in :py:attr:`pw_cc_flag_group.flags` if the + specified build variable is **NOT** set. |