1.. _module-pw_toolchain: 2 3============ 4pw_toolchain 5============ 6.. pigweed-module:: 7 :name: pw_toolchain 8 9GN toolchains function both as a set of tools for compilation and as a workspace 10for evaluating build files. The same compilations and actions can be executed by 11different toolchains. Each toolchain maintains its own set of build args, and 12build steps from all toolchains can be executed in parallel. 13 14--------------------------------- 15C/C++ toolchain support libraries 16--------------------------------- 17``pw_toolchain`` provides some toolchain-related C/C++ libraries. 18 19``std:abort`` wrapper 20===================== 21The `std::abort <https://en.cppreference.com/w/cpp/utility/program/abort>`_ 22function is used to terminate a program abnormally. This function may be called 23by standard library functions, so is often linked into binaries, even if users 24never intentionally call it. 25 26For embedded builds, the ``abort`` implementation likely does not work as 27intended. For example, it may pull in undesired dependencies (e.g. 28``std::raise``) and end in an infinite loop. 29 30``pw_toolchain`` provides the ``pw_toolchain:wrap_abort`` library that replaces 31``abort`` in builds where the default behavior is undesirable. It uses the 32``-Wl,--wrap=abort`` linker option to redirect to ``abort`` calls to 33``PW_CRASH`` instead. 34 35arm-none-eabi-gcc support 36========================= 37Targets building with the GNU Arm Embedded Toolchain (``arm-none-eabi-gcc``) 38should depend on the ``pw_toolchain/arm_gcc:arm_none_eabi_gcc_support`` 39library. In GN, that target should be included in ``pw_build_LINK_DEPS``. In 40Bazel, it should be added to `link_extra_lib 41<https://bazel.build/reference/be/c-cpp#cc_binary.link_extra_lib>`__ or 42directly to the `deps` of any binary being build with that toolchain: 43 44.. code-block:: python 45 46 cc_binary( 47 deps = [ 48 # Other deps, omitted 49 ] + select({ 50 "@platforms//cpu:armv7e-m": [ 51 "@pigweed//pw_toolchain/arm_gcc:arm_none_eabi_gcc_support", 52 ], 53 "//conditions:default": [], 54 }), 55 ) 56 57Newlib OS interface 58------------------- 59`Newlib <https://sourceware.org/newlib/>`_, the C Standard Library 60implementation provided with ``arm-none-eabi-gcc``, defines a set of `OS 61interface functions <https://sourceware.org/newlib/libc.html#Stubs>`_ that 62should be implemented. Newlib provides default implementations, but using these 63results in linker warnings like the following: 64 65.. code-block:: none 66 67 readr.c:(.text._read_r+0x10): warning: _read is not implemented and will always fail 68 69Most of the OS interface functions should never be called in embedded builds. 70The ``pw_toolchain/arg_gcc:newlib_os_interface_stubs`` library, which is 71provided through ``pw_toolchain/arm_gcc:arm_none_eabi_gcc_support``, implements 72these functions and forces a linker error if they are used. It also 73automatically includes a wrapper for ``abort`` for use of ``stdout`` and 74``stderr`` which abort if they are called. 75 76If you need to use your own wrapper for ``abort``, include the library directly 77using ``pw_toolchain/arm_gcc:newlib_os_interface_stubs``. 78 79pw_toolchain/no_destructor.h 80============================ 81.. doxygenclass:: pw::NoDestructor 82 83builtins 84======== 85builtins are LLVM's equivalent of libgcc, the compiler will insert calls to 86these routines. Setting the ``dir_pw_third_party_builtins`` gn var to your 87compiler-rt/builtins checkout will enable building builtins from source instead 88of relying on the shipped libgcc. 89 90.. toctree:: 91 :hidden: 92 :maxdepth: 1 93 94 bazel 95 gn 96