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