1.. _module-pw_build-linker_scripts: 2 3============== 4Linker Scripts 5============== 6.. pigweed-module-subpage:: 7 :name: pw_build 8 9``pw_build`` provides utilities for working with linker scripts in embedded 10projects. If using the ``GN`` or ``Bazel`` build systems you can preprocess your 11linker script using the C preprocessor with the ``pw_linker_script`` rules. 12 13- GN :ref:`module-pw_build-gn-pw_linker_script` 14- Bazel :ref:`module-pw_build-bazel-pw_linker_script` 15 16--------------------- 17Linker Script Helpers 18--------------------- 19 20``PW_MUST_PLACE`` 21================= 22.. doxygengroup:: pw_must_place 23 :content-only: 24 :members: 25 26``LinkerSymbol`` 27================ 28.. doxygenclass:: pw::LinkerSymbol 29 :members: 30 31.. note:: 32 33 ``LinkerSymbol`` does not support, and is not necessary for, symbols that 34 communicate a pointer value (i.e. an address). For those, simply define an 35 extern variable of the pointed-to type, e.g.: 36 37 .. code-block:: cpp 38 39 extern "C" uint32_t PTR_SYM; 40 41``LinkerSymbol`` is superior to the traditional ``extern uint8_t FOO;`` 42``(uint32_t)&FOO`` method because it catches subtle errors: 43 44* Missing ``extern`` specifier: 45 46 .. code-block:: none 47 48 error: use of deleted function 'pw::build::LinkerSymbol::LinkerSymbol()' 49 | LinkerSymbol oops; 50 | ^~~~ 51 52* Missing ``&`` operator: 53 54 .. code-block:: none 55 56 error: invalid cast from type 'pw::build::LinkerSymbol' to type 'uint32_t' {aka 'long unsigned int'} 57 | uint32_t val = (uint32_t)FOO_SYM; 58 | ^~~~~~~~~~~~~~~~~ 59